Skip to main content
Manage operations under a single namespace. Aggregates ps (list), show (inspect), and kill (cancel), and adds multi-UUID support to show and cancel so several operations can be acted on in one call. op is the short alias.

​
Subcommands

​
Examples

​
Help output

The top-level op command is a dispatcher: by itself it only prints usage and routes to the three subcommands described below.
$ contree op —help
usage: contree operation [-h] {list,ls,show,sh,cancel,kill,k,wait,w} …

Manage operations (list, inspect, cancel).

Aggregates ps/show/kill under a single namespace, and adds multi-UUID
support to “show“ and “cancel“ so several operations can be acted
on in one invocation.

Subcommands:
  list (ls)             List operations. “contree ps“ is an alias.
  show UUID [UUID…]   Show one or more operation results.
  cancel UUID [UUID…] Cancel one or more operations (or —all).

positional arguments:
  {list,ls,show,sh,cancel,kill,k,wait,w}
    list (ls)           List operations
    show (sh)           Show one or more operation results
    cancel (kill, k)    Cancel one or more operations
    wait (w)            Wait for operations to reach a terminal status

options:
  -h, —help            show this help message and exit

for coding agents:
  list/show are read-only; cancel mutates remote state
  show and cancel accept multiple UUIDs in one invocation
  show supports @N session-history references inherited from `contree show`

agent note:
  Before using this command in an automated workflow, read:
    contree agent

​
op list – dynamic columns

contree op list (alias op ls) accepts the same filter flags as contree ps (-a, --status STATUS, -K KIND, --since, --until, -q/--quiet) and shares its rendering pipeline. Reach for it when you want the operations namespace to feel symmetric with the multi-UUID show and cancel; otherwise contree ps is just as good. -S is the global session flag and only works BEFORE the subcommand.
$ contree op list —help
usage: contree operation list [-h] [-q] [-a]
                              [—status {P,PENDING,A,ASSIGNED,E,EXECUTING,S,SUCCESS,F,FAILED,C,CANCELLED}]
                              [-k {image_import,instance}] [—since SINCE] [—until UNTIL]
                              [-M SHOW_MAX]

List operations. “contree ps“ is an alias of this command.

options:
  -h, —help            show this help message and exit
  -q, —quiet           Only show UUIDs, useful for scripting
  -a, —all             Show all operations (default: active only)
  —status {P,PENDING,A,ASSIGNED,E,EXECUTING,S,SUCCESS,F,FAILED,C,CANCELLED}
                        Filter by status (default: EXECUTING only, unless -a is used)
  -k, —kind {image_import,instance}
                        Filter by operation kind
  —since SINCE         Parse +/- intervals (bare seconds or smhdMy) or ISO/date to UTC datetime.
  —until UNTIL         Show operations before. Parse +/- intervals (bare seconds or smhdMy) or
                        ISO/date to UTC datetime.
  -M, —show-max SHOW_MAX
                        Show at most this many operations, useful for —all with large history
                        (default: 1000)

for coding agents: read-only command
The listing renders every scalar top-level field the API returns, not a hard-coded subset. When the server adds a new field (for example cost, project_id, started_at), it appears in the output without a CLI release. Nested structures (metadata, result, tags) are filtered out – use op show UUID for the detail view. Known fields are lightly typed: Column order follows the API response, with one exception: error is pinned to the last column. Long free-form error messages would otherwise push the rest of the row out of alignment.

​
op show – multiple UUIDs

Each UUID is fetched and rendered through the same code path as contree show, so cached terminal results and history references work uniformly. Accepted reference forms (mirroring session rollback syntax with a git-style alias):
  • @, :, or HEAD – the operation at the active branch tip.
  • @N (or :N, bare N) – absolute history id.
  • @-N, :-N, or HEAD~N – walk N steps back from the tip.
  • HEAD~ – shorthand for HEAD~1.
  • @+N (or :+N) – walk N steps forward from the tip, picking the latest child at each branch point.
On API errors (e.g. 404 for an unknown UUID), the command logs the failure and continues with the remaining UUIDs, exiting with status 1 at the end.
$ contree op show —help
usage: contree operation show [-h] [—raw] UUID_OR_REF [UUID_OR_REF …]

Fetch and display the result of each given operation. Same per-UUID behaviour as `contree show`:
terminal results are cached; @N references resolve against session history.

positional arguments:
  UUID_OR_REF  Operations to inspect. Accepts UUIDs and session-history references: @ or HEAD for
               the active branch tip, @N for an absolute history id, @-N or HEAD~N for N steps
               back, @+N for N steps forward.

options:
  -h, —help   show this help message and exit
  —raw        Print each operation’s JSON payload as JSONL (one object per line) to stdout.
               Round-trips through the typed operation model, so fields the model doesn’t know
               about are dropped. Skips formatter routing and derived columns; streams cleanly
               into `jq -c`. Useful for debugging or for fields the table view omits.

for coding agents: read-only command accepts multiple UUIDs; each rendered as its own row
With table output (-o table) and several UUIDs, each operation currently renders as its own mini-table. Use default or json for a unified stream view across multiple UUIDs.

​
op wait – block until completion

Poll the given operations until each reaches a terminal status (SUCCESS, FAILED, CANCELLED) and print one row per completion with the columns uuid, status, exit_code, timed_out, duration (and every other scalar field the API returns; error is pinned to the last column). --all waits for every currently active operation in the project. --timeout SECONDS (default 60) caps the wait — when the deadline hits, the command emits one extra row per unfinished operation with timed_out=true and the operation’s last observed status (e.g. EXECUTING), then exits with status 1. status is the server’s word: it reflects orchestration (did the API run the job?), not what the sandbox process did with its exit code. The exit code is a separate column. The CLI’s own exit status is 1 whenever any operation finished non-SUCCESS, or the actual exit_code when a SUCCESS op exited non-zero — so op wait UUID && next-step composes correctly with sandbox commands like run -- false.
op wait is a pure observer: it polls operation status and prints rows, but it never updates session state. In particular, the detached-<op-uuid> branch created when you ran contree run -d keeps pointing at the starting image — op wait does not advance it to the result image. The pattern therefore fits non-image-producing runs (--disposable) most cleanly; for non-disposable fan-out, the result image of each leg lives only on the server and you must recover it explicitly (see the non-disposable example below).
--all is project-scoped. If multiple agents (or multiple shell sessions) share the same project, op wait --all will block on every active operation across all of them — not just the ones you launched. The wait still completes correctly; it just waits for more than you might expect. For multi-agent setups, prefer the explicit op wait UUID1 UUID2 ... form with the UUIDs you actually own.
$ contree op wait —help
usage: contree operation wait [-h] [-a] [-t TIMEOUT] [UUID_OR_REF …]

Poll the given operations until each reaches a terminal status (SUCCESS, FAILED, CANCELLED) and
print one row per completion. With —all, waits for every currently active operation (PENDING,
ASSIGNED, EXECUTING).

positional arguments:
  UUID_OR_REF           Operations to wait for. Accepts UUIDs and session-history references
                        (HEAD, HEAD~N, @, @N, @-N, @+N, :N, bare N).

options:
  -h, —help            show this help message and exit
  -a, —all             Wait for every active operation
  -t, —timeout TIMEOUT
                        Fail with exit code 1 if not all operations reach a terminal status within
                        this many seconds (default: 60)

for coding agents: read-only command (polls the API; no state mutation) fails with exit code 1 if
—timeout is hit before all complete exit code 1 also when any operation finished non-SUCCESS
Preferred — --disposable fan-out, no image to track. Note the global -o json before run so jq sees JSON; the default formatter is plain.
Non-disposable fan-out — must recover the chosen leg’s image yourself:
Block on the whole project (5 min cap):

​
op cancel – multiple UUIDs or --all

Either pass UUIDs explicitly or use --all to cancel every active operation (PENDING, ASSIGNED, EXECUTING). Combining both is allowed: --all wins, and the explicit UUIDs are ignored with a WARNING. As with op show, errors on individual UUIDs do not abort the run; the command exits 1 if any cancellation failed.
$ contree op cancel —help
usage: contree operation cancel [-h] [-a] [UUID_OR_REF …]

Cancel each given operation. With —all, cancels every active operation (PENDING, ASSIGNED,
EXECUTING).

positional arguments:
  UUID_OR_REF  Operations to cancel. Accepts UUIDs and session-history references (HEAD, HEAD~N,
               @, @N, @-N, @+N, :N, bare N).

options:
  -h, —help   show this help message and exit
  -a, —all    Cancel every active operation

for coding agents: mutating command pass UUIDs to cancel specific operations or —all for
everything

​
Comparison with the top-level commands

contree ps and contree kill are top-level shortcuts that share the same argparse setup and handler as op list / op cancel respectively — there is no separate implementation. contree show keeps its own single-UUID handler (the multi-UUID op show wraps it).

​
See also