Operations

Observing and controlling runs: ps, logs, ui, inspect, cancel, down, panic, and the how-to runbook.

Every xiv workflow is a long-running Smithers run living in SMITHERS_HOME (default ~/.smithers). These commands are thin passthroughs: xiv <command> [args...] forwards straight to smithers <command> [args...] executed in SMITHERS_HOME, so any flag the underlying smithers command accepts works here too. They require the pack to be installed (xiv init) and error otherwise.

Observing runs

xiv ps          # what's running right now — the first check for "is it still going?"
xiv logs        # run output: what step a run is on, and failures
xiv ui          # live workflow graph in the browser — best for multi-step runs
xiv inspect     # detailed state for a specific run

For stacked features, xiv stack triage --feature <slug> is the higher-level view — it tells you the next action, not just what's running. See xiv stack.

Working vs. stuck

Runs are multi-agent and bursty — long quiet stretches during a hard implement or review step are normal. Judge by progress, not silence:

• Step advancing in xiv ui, or new lines in xiv logs over time → working. Leave it alone.
• No progress for a long time and the logs show an error, a prompt waiting on input, or a crashed process → stuck. Act.
• Not sure → check xiv logs for the last event before deciding. Don't cancel a run just because it's quiet.

Stopping runs

xiv cancel <run>    # cancel one specific run
xiv down            # cancel ALL active/orphaned runs

Most workflows are resumable — Smithers persists each completed step, so re-running resumes from the last persisted step instead of redoing finished work (xiv stack build skips built entries). Prefer resuming a wedged run over cancelling and restarting from scratch.

xiv panic

The credit-burn kill switch.

xiv panic

panic is an alias for xiv down — it cancels every active and orphaned run. The difference is the situation it's named for: when a workflow is actively looping or burning credits, don't deliberate, don't ask — kill everything now and diagnose afterward. The "confirm with the human first" caveat on down applies to clearing quiet, stale runs; panic is for stopping a live fire.

After a panic: read xiv logs for what the run was doing, fix the cause, then resume (re-run the command; it picks up from persisted state).

xiv how-to

Print the orchestration runbook.

xiv how-to

Prints the authoritative, current guide to driving a Linear feature to completion with xiv stack: the triage-driven loop, the action-to-command mapping, multi-repo notes, prerequisites, cost levers, and the hard rules. It's the document the xiv-operator skill points agents at to get up to speed — prefer it over anything memorized, since it ships with the CLI and is always in sync with the installed version.

When to escalate instead of act

Stop and tell a human — with what you saw — rather than improvising on:

• auth or token expiry (gh, Linear, a model provider),
• jj or git merge/rebase conflicts,
• the same test or validation step failing repeatedly,
• any state you can't confidently classify.

And never "unstick" a run by merging a PR or force-pushing.

Going deeper

The full smithers CLI has more than xiv exposes (up, graph, why, events, supervise, and others) — reach for raw smithers in SMITHERS_HOME only when these passthroughs don't cover what you need. For the concepts behind runs (tasks, the persist-each-step render loop, why re-running is safe), see How It Works.