Skip to Content
How-to guidesStart a run from the CLI

Start and manage a run from the CLI

Start an agent on a task from your terminal and watch it work. Hand off a code review before a meeting, or call marshal run from a script and let its exit code tell you whether the agent succeeded. The command starts a headless run from a manifest and a task.

Before you start

  • Role: you can use the manifest.
  • The CLI is installed and you are signed in with marshal login. See Install the CLI.
  • A manifest. See Create a manifest.
  • Available when your administrator enables runs and deputies.

Steps

  1. Start the run:

    marshal run --manifest my-manifest --task "review the repo and list risks" --follow
    FlagMeaning
    --manifestRequired. A manifest name or ID.
    --taskRequired. The prompt for the agent.
    --followStream the transcript until the run ends.
    --titleA short name shown in the Runs list. Default: made from the task.
    --timeoutThe time budget, for example 30m. Default: your org’s default time budget, or 15m when the org has none.
    --output-modeWhere the run’s output comes from: file (the agent writes /workspace/output.json) or transcript (the agent’s final message). Default is file.
    --permission-modeauto approves every permission request. deny refuses every request and needs --driver-mode acp. Default is auto.
    --driver-modeHow the agent is driven: acp, print or exec. Default is the runtime’s preferred mode.
    --jsonPrint the run as one JSON object on stdout, and send everything else to stderr.
    --verboseWith --follow, also print the agent runtime’s diagnostic lines.
    --runtimeThe agent runtime. Default is claude-code.
    --compute-classA size name such as medium, or a compute class ID. Optional.
    --keep-on-failureIf the run fails, keep its space up for 24 hours so you can look inside.

  2. Without --follow, the command prints the run ID and a hint: follow with: marshal runs logs <run-id>. Run that command to stream the transcript.

  3. See your runs with marshal runs list. It prints the ID, status, runtime, and the run’s title.

  4. See one run with marshal runs get <run-id>. It prints the status, runtime, space, task, and, when there are any, the stop reason, output and error. A run that ended on its time budget says so here too.

  5. Send a note to a run that is still working:

    marshal deputies message <run-id> "check staging before you touch prod"

  6. Change the time budget of a live run with exactly one of these:

    marshal runs timeout <run-id> --add 15m
marshal runs timeout <run-id> --pause
marshal runs timeout <run-id> --resume

    --add must be at least 1m. --pause stops the timer only. The agent keeps working.

  7. Cancel with marshal runs cancel <run-id>. You can also pass the ID of a queued launch.

To pick a finished run up again, run marshal runs continue <run-id> --message "...", or use the web app. See Continue a finished run.

Read the result in a script

Add --json and a script gets one JSON object on stdout with the run’s id, status, stop_reason, output, error, timeout_secs, url and continues_run_id. The transcript and progress lines go to stderr, so stdout holds only the object.

marshal run --manifest my-manifest --task "summarize the open changes" \
  --output-mode transcript --follow --json 2>/dev/null | jq '.status, .output'

With --follow, the object describes the final run, and the exit code is non-zero unless that run succeeded. Without --follow, it describes the run as created. marshal runs get <run-id> --json prints the same object for any run, and marshal runs list --json prints an array. The CLI reference lists every field.

What you should see

  • After marshal run: run <run-id> started (space <space-id>), a title: line when the run has a title, and a timeout line with the time budget the run got, for example timeout 2h.
  • With --json, those lines appear on stderr and stdout holds the JSON object.
  • If the time budget ends the run, the command says that the run timed out, shows the budget it had, and points to --timeout and marshal runs timeout --add.
  • With --follow: the agent’s output as it works. At the end, a line like ── run <run-id>: succeeded, then output: or error: when there is one.
  • If the run parks to wait for an answer, a line says it is parked and the command keeps waiting. Once someone answers, the output carries on in the run that continues the work.
  • The command exits with an error code when the final run ends in any status other than succeeded. This makes it safe to use in scripts.
  • Add --verbose to also see the agent runtime’s own diagnostic lines.
  • After marshal deputies message: message queued for the agent's next turn. With --interrupt, a line that says the current turn is stopping so the agent reads it now.
  • After marshal runs cancel: run <run-id> canceling.

Next

Start a run in the web and follow it: open the same run on its run page to see changes, ports and cost.

Start a run in the webSteer a live run