operation - Manage operations

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

Subcommand

Aliases

Description

list

ls

List operations. Same flags as contree ps.

show UUID [UUID...]

sh

Show one or more operation results.

wait UUID [UUID...]

w

Wait for operations to reach a terminal status (or --all).

cancel UUID [UUID...]

kill, k

Cancel one or more operations (or --all).

Examples

# List active operations (same as `contree ps`)
contree op list
contree op ls
contree op ls -a --status FAILED # all flags from ps are accepted

# Inspect a single operation
contree op show 3f2a7b...

# Inspect several operations at once
contree op show 3f2a7b... a1b2c3... 9d8e7f...

# History references (inherited from `contree show`)
contree op show @5 @4 @3

# Cancel one or more operations
contree op cancel 3f2a7b...
contree op cancel a1b2c3... 9d8e7f...

# Cancel every active operation
contree op cancel --all

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 {image_import,instance}, --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_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:

Field

Transform

created_at, started_at, finished_at, updated_at

parsed to UTC datetime

duration

wrapped as timedelta (total_seconds() in JSON)

error

None is rendered as empty string

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 full server payload as JSONL (one JSON object per line) to                stdout, verbatim. 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

Note

With table output (-f 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.

Important

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).

Warning

--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 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 -f json before run so jq sees JSON; the default formatter is plain.

A=$(contree -f json run -d --disposable -- pytest tests/a | jq -r .uuid)
B=$(contree -f json run -d --disposable -- pytest tests/b | jq -r .uuid)
C=$(contree -f json run -d --disposable -- pytest tests/c | jq -r .uuid)
contree op wait "$A" "$B" "$C"
contree op show "$A" "$B" "$C"          # stdout/stderr per leg

Non-disposable fan-out — must recover the chosen leg’s image yourself:

A=$(contree -f json run -d -- apt-get install -y curl | jq -r .uuid)
B=$(contree -f json run -d -- apt-get install -y wget | jq -r .uuid)
contree op wait "$A" "$B"

# Pull the result image out and bind it back into the session,
# or tag it for later reuse.
IMG_A=$(contree -f json op show "$A" | jq -r .image)
contree use "$IMG_A"
contree tag "$IMG_A" feature/curl-tools

Block on the whole project (5 min cap):

contree op wait --all --timeout 300

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 
# Mixed: --all still wins, "ignored-1" is not cancelled
contree op cancel --all ignored-1

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).

Need

Use

List active operations

contree ps or contree op ls

Inspect one operation

contree show UUID or contree op show UUID

Inspect multiple

contree op show UUID1 UUID2 ...

Block on multiple

contree op wait UUID1 UUID2 ...

Block on everything active

contree op wait --all

Cancel one operation

contree kill UUID or contree op cancel UUID

Cancel multiple

contree kill UUID1 UUID2 ... or contree op cancel UUID1 UUID2 ...

Cancel everything active

contree kill --all or contree op cancel --all

See also