mirror of
https://github.com/stablyai/orca.git
synced 2026-10-30 16:47:34 +00:00
docs(cli): explain automation prechecks and folder workspace removal (#34523)
This commit is contained in:
Brennan Benson
@@ -38,9 +38,9 @@ orca automations create \
|
||||
|
||||
When you omit both target flags, Orca resolves the enclosing worktree from the current shell directory when it can.
|
||||
|
||||
## Precheck before a run
|
||||
## Precheck before a scheduled run
|
||||
|
||||
Skip scheduled work when a cheap shell probe fails (non-zero exit records a skipped run):
|
||||
Use `--precheck <command>` to run a shell command only before scheduled runs. Exit code `0` continues; any other exit, error, or timeout skips the run. Set the time limit with `--precheck-timeout <seconds>` (default `60`). Skips appear in Orca run history and `orca automations runs --id <automationId> --json` with status `skipped_precheck`.
|
||||
|
||||
```bash
|
||||
orca automations create \
|
||||
@@ -145,6 +145,8 @@ Use `edit` to change the name, prompt, provider, target, schedule, or enabled st
|
||||
|
||||
After creating an automation, trigger it manually to check the prompt and target before waiting for the next scheduled time:
|
||||
|
||||
**Run now** in Orca and `orca automations run` intentionally bypass the precheck, so you can test the automation or override its scheduled condition.
|
||||
|
||||
```bash
|
||||
orca automations run <automationId> --json
|
||||
orca automations runs --id <automationId> --json
|
||||
|
||||
@@ -16,5 +16,12 @@ ORCA automations remove <automationId> --json
|
||||
|
||||
Schedules accept `hourly`, `daily`, `weekdays`, `weekly`, 5-field cron, or RRULE. Use `--time <HH:MM>` with `daily`/`weekdays`/`weekly`, and `--day <0-6>` only with `weekly` where Sunday is `0`.
|
||||
|
||||
Use `--precheck <command>` to run a shell command only before scheduled runs. Exit code `0` continues; any other exit, error, or timeout skips the run. Set the time limit with `--precheck-timeout <seconds>` (default `60`). Skips appear in Orca run history and `ORCA automations runs --id <automationId> --json` with status `skipped_precheck`.
|
||||
|
||||
**Run now** in Orca and `ORCA automations run <automationId>` intentionally bypass the precheck, so you can test the automation or override its scheduled condition.
|
||||
|
||||
Use `--repo <selector>` for a new worktree per run, or `--workspace <selector>` / `--workspace-mode existing` for an existing Orca worktree. `--repo` and `--workspace` are mutually exclusive. Use `--reuse-session` only for existing-workspace automations; if the previous terminal is gone, Orca falls back to a fresh session. Prefer `--disabled` while testing setup.
|
||||
|
||||
On a plain folder project, `new_per_run` creates separate Orca workspace entries pointing to the same folder. Removing the automation leaves these entries available. To remove one, copy its full `id` from `ORCA worktree list --json`, then run `ORCA worktree rm --worktree "id:<full-instance-id>"`. This removes that entry and stops its sessions without deleting the folder or touching Git. Select by instance ID rather than the shared path; the folder project root cannot be removed with this command.
|
||||
|
||||
Use `--extra-agent-args="--model opus --effort high --add-dir docs"` to add arguments after the host's default agent Arguments on every fresh run (always pass it with `=`, since the value starts with `--`). Only model and effort options, plus Claude's `--add-dir`, are accepted, for `claude`, `codex`, `codebuddy`, `cursor`, `grok`, and `omp`. Model or effort in the extras replaces the default's. Extras can't be combined with `--reuse-session`. `--extra-agent-args=` on edit clears them.
|
||||
|
||||
@@ -764,7 +764,14 @@ const ORCA_CLI_AUTOMATIONS_REFERENCE_MARKDOWN = [
|
||||
"",
|
||||
"Schedules accept `hourly`, `daily`, `weekdays`, `weekly`, 5-field cron, or RRULE. Use `--time <HH:MM>` with `daily`/`weekdays`/`weekly`, and `--day <0-6>` only with `weekly` where Sunday is `0`.",
|
||||
"",
|
||||
"Use `--precheck <command>` to run a shell command only before scheduled runs. Exit code `0` continues; any other exit, error, or timeout skips the run. Set the time limit with `--precheck-timeout <seconds>` (default `60`). Skips appear in Orca run history and `ORCA automations runs --id <automationId> --json` with status `skipped_precheck`.",
|
||||
"",
|
||||
"**Run now** in Orca and `ORCA automations run <automationId>` intentionally bypass the precheck, so you can test the automation or override its scheduled condition.",
|
||||
"",
|
||||
"Use `--repo <selector>` for a new worktree per run, or `--workspace <selector>` / `--workspace-mode existing` for an existing Orca worktree. `--repo` and `--workspace` are mutually exclusive. Use `--reuse-session` only for existing-workspace automations; if the previous terminal is gone, Orca falls back to a fresh session. Prefer `--disabled` while testing setup.",
|
||||
"",
|
||||
"On a plain folder project, `new_per_run` creates separate Orca workspace entries pointing to the same folder. Removing the automation leaves these entries available. To remove one, copy its full `id` from `ORCA worktree list --json`, then run `ORCA worktree rm --worktree \"id:<full-instance-id>\"`. This removes that entry and stops its sessions without deleting the folder or touching Git. Select by instance ID rather than the shared path; the folder project root cannot be removed with this command.",
|
||||
"",
|
||||
"Use `--extra-agent-args=\"--model opus --effort high --add-dir docs\"` to add arguments after the host's default agent Arguments on every fresh run (always pass it with `=`, since the value starts with `--`). Only model and effort options, plus Claude's `--add-dir`, are accepted, for `claude`, `codex`, `codebuddy`, `cursor`, `grok`, and `omp`. Model or effort in the extras replaces the default's. Extras can't be combined with `--reuse-session`. `--extra-agent-args=` on edit clears them.",
|
||||
"",
|
||||
].join('\n')
|
||||
|
||||
@@ -60,7 +60,9 @@ export const AUTOMATION_COMMAND_SPECS: CommandSpec[] = [
|
||||
'--host takes local, ssh:<target-id>, runtime:<environment-id>, or the bare host name `orca host list` prints for any of them.',
|
||||
'Use --source-context with a JSON TaskSourceContext when task/provider data should come from a specific host/account; pass null on edit to clear it.',
|
||||
'Use --workspace to run in an existing worktree; otherwise the automation creates a new worktree per run.',
|
||||
'Use --precheck to run a bounded command before scheduled runs; exit code 0 continues, anything else records a skipped run.',
|
||||
'Use --precheck to run a command only before scheduled runs; exit code 0 continues, any other exit, error, or timeout skips the run.',
|
||||
'Use --precheck-timeout <seconds> to set the time limit (default 60 seconds). Skips appear in Orca run history and orca automations runs --id <automation-id> as skipped_precheck.',
|
||||
'Run now in Orca and orca automations run intentionally bypass the precheck so you can test or override the scheduled condition.',
|
||||
'Use --reuse-session only with existing-workspace automations to submit later runs to the previous live automation session when it is still available. Use --fresh-session to disable reuse.',
|
||||
'Use --extra-agent-args="--model opus --effort high" to add arguments after the host\'s default agent Arguments on each fresh run. Only model, effort, and a few safe options are accepted (Claude, Codex, CodeBuddy, Cursor, Grok, OMP); extras cannot be combined with --reuse-session. On edit, --extra-agent-args= clears them.'
|
||||
],
|
||||
@@ -111,6 +113,7 @@ export const AUTOMATION_COMMAND_SPECS: CommandSpec[] = [
|
||||
positionalArgs: ['id'],
|
||||
notes: [
|
||||
'Use the full automation UUID from orca automations list; shortened prefixes are not accepted.',
|
||||
'Like Run now in Orca, this manually starts a run without executing the precheck; prechecks gate scheduled runs only.',
|
||||
'A queued or dispatching run has been accepted but may not have a workspace or terminal yet. Use orca automations runs --id <automation-id> to follow its progress.'
|
||||
],
|
||||
examples: [
|
||||
|
||||
@@ -137,11 +137,13 @@ export const CORE_COMMAND_SPECS: CommandSpec[] = [
|
||||
['worktree', 'delete']
|
||||
],
|
||||
destructive: true,
|
||||
summary: 'Remove a worktree from Orca and git',
|
||||
summary: 'Remove a Git worktree or a folder workspace entry from Orca',
|
||||
usage:
|
||||
'orca worktree rm --worktree <selector> [--force] [--run-hooks] [--allow-failed-archive-hook] [--json]',
|
||||
allowedFlags: [...GLOBAL_FLAGS, 'worktree', 'force', 'run-hooks', 'allow-failed-archive-hook'],
|
||||
notes: [
|
||||
'For a non-root folder workspace, removes its Orca entry and stops its sessions without deleting the folder or touching Git. The folder project root cannot be removed with this command.',
|
||||
'Use --worktree "id:<full-instance-id>" with the full id from orca worktree list --json to select one folder workspace; several entries can share the same path.',
|
||||
'Repo-defined orca.yaml archive hooks are skipped unless --run-hooks is passed.',
|
||||
'With --run-hooks, a failed archive hook blocks the removal: nothing is stopped, deleted or deregistered, and the command exits non-zero with error code worktree_archive_hook_failed. --force does not waive this.',
|
||||
'Pass --allow-failed-archive-hook to delete anyway after the hook has run and failed; the waived failure is reported back on result.archiveHookOverride. It requires --run-hooks and is rejected without it, because with no hook running there is no failure to waive.',
|
||||
|
||||
Reference in New Issue
Block a user