Skip to content

CLI flags#

The output of blyte --help and of each subcommand's --help. Behaviour is described in Running tasks, the workflow, Providers and Security.

A lean coding-agent harness with a sealed verification gate

Usage: blyte [OPTIONS] [PROMPT] [COMMAND]

Commands:
  init        Detect this repository's checks and write blyte.toml
  dashboard   Serve a local dashboard of running and recent jobs
  dispatch    Run one task in its own git worktree (.wt/<id>, branch wip/<id>) and print a JSON summary
  review      Show what a dispatched run did: commits, files, tree state, report, and optionally the diff
  clean       Remove finished worktrees and merged branches
  status      Show what a dispatch is doing
  wait        Wait until dispatched runs finish (all of them, or the first with --any) and print one line per finished run
  skill       Install or print the Claude Code skill for the plan, delegate, review workflow
  update      Replace this binary with the latest release (the old one is kept as blyte.prev)
  cost        Show orchestrator and implementer costs
  statusline  Print Claude Code's status line with blyte costs
  plan        List a plan's tasks with their state and the command to dispatch each ready one
  help        Print this message or the help of the given subcommand(s)

Arguments:
  [PROMPT]  Direct task prompt to run in single-shot / headless mode

Options:
  -g, --gate <GATE>
          Verification gate command (e.g. 'pytest', 'cargo test'). Several steps may be given one per line: every step runs and all failures are reported together
      --orchestrate
          Run blyte as the orchestrator: plan, dispatch implementers with `blyte dispatch`, review and merge
      --dispatch-cmd <DISPATCH_CMD>
          Command to run on the host when the orchestrator delegates work via the `dispatch` tool
      --context <CONTEXT>
          Context strategy: 'conversational' (append-all chat) or 'folded' (append-only chat, oldest half folded into digests past a budget) [default: folded] [possible values: conversational, folded]
  -m, --model <MODEL>
          Model identifier or provider selection
      --container <CONTAINER>
          Run inside an isolated container workspace instead of local host
      --max-turns <MAX_TURNS>
          Maximum turn budget [default: 25]
      --max-gates <MAX_GATES>
          Maximum verification gate attempts before failing [default: 5]
      --rollback[=<ROLLBACK>]
          Enable automatic rollback to baseline git commit if gate fails (disable with --rollback=false) [default: true] [possible values: true, false]
      --container-workdir <CONTAINER_WORKDIR>
          Working directory inside the container when --container is set [default: /workspace]
      --max-seconds <MAX_SECONDS>
          Wall-clock budget in seconds; the run stops itself and reports when it is spent
      --max-cost <MAX_COST_USD>
          Maximum spend in USD; the run stops before a model call once reached
      --report <REPORT>
          Write a JSON run report to this path when the headless run exits
      --fold-budget <FOLD_BUDGET>
          Approximate token budget for the verbatim tail before folding (folded context; default 48000)
      --sandbox <SANDBOX>
          Sandbox the commands blyte runs on this machine (macOS Seatbelt, Linux Landlock): 'on' or 'off' [default: on] [possible values: on, off]
      --network <NETWORK>
          Let commands blyte runs connect out: 'on' or 'off' (default 'on'). 'off' needs the sandbox [default: on] [possible values: on, off]
      --allow-read <ALLOW_READ>
          Let sandboxed commands read this path despite the credential deny-list (repeatable)
      --pass-env <PASS_ENV>
          Pass this environment variable to commands even though it looks like a credential (repeatable)
      --read-root <DIR>
          Directory allowed for reading with the read and grep tools (repeatable)
      --no-gate-slot
          Gates in this run do not take a machine-wide slot
      --research
          Whether this is a research run: periodically remind the model to keep report.md updated
      --claim-check
          Research run: check report.md's claims against their cited lines
  -h, --help
          Print help
  -V, --version
          Print version

blyte init#

Detect this repository's checks and write blyte.toml

Usage: blyte init [OPTIONS]

Options:
      --force                   Overwrite an existing blyte.toml
      --print                   Print the file instead of writing it
      --no-verify               Skip gate verification on HEAD
      --sandbox <SANDBOX>       Sandbox local command execution: 'on' or 'off' (default 'on') [default: on] [possible values: on, off]
      --step-timeout <SECONDS>  Timeout in seconds for each verification step (default 600) [default: 600]
  -h, --help                    Print help

blyte dashboard#

Serve a local dashboard of running and recent jobs

Usage: blyte dashboard [OPTIONS]

Options:
      --port <N>        Port to listen on (0 for a free port) [default: 7171]
      --root <DIR>      Directory holding repositories or worktrees (repeatable)
      --runs-dir <DIR>  Directory holding run logs and reports (repeatable)
      --hours <N>       How far back finished jobs are listed, in hours [default: 24]
      --open            Open the dashboard in the default browser
  -h, --help            Print help

A job with no report counts as running only when its PID is alive and that process started no later than 60 seconds after the job's started_at (guarding against reused PIDs). In the runs-dir layout, <id>.json is recognized as an agy summary: jobs with this file report status finished (or error), with their elapsed duration, turn count, and response text.

blyte dispatch#

Run one task in its own git worktree (.wt/<id>, branch wip/<id>) and print a JSON summary

Usage: blyte dispatch [OPTIONS] <ID> [TASK_FILE]

Arguments:
  <ID>         Identifier for this dispatch (used for worktree and branch wip/<id>)
  [TASK_FILE]  Path to the task description markdown file; optional with --plan and --plan-task, which take the task from the plan

Options:
  -g, --gate <GATE>                The check command; several lines are several steps, all of which must pass
      --tag <TEXT>                 Tag for this dispatch (repeatable)
      --plan <PATH>                Path to the plan file this dispatch belongs to
      --plan-task <TEXT>           Plan task this dispatch implements
      --base <BASE>                The commit a new worktree starts from [default: HEAD]
      --research                   Run read-only research: scratch repository, report gate, findings in report.md
      --report-to <PATH>           Copy the finished research report to this path (only with --research)
  -m, --model <MODEL>              Model identifier or provider selection
      --max-seconds <MAX_SECONDS>  Wall-clock budget in seconds (default 3600)
      --max-turns <MAX_TURNS>      Maximum turn budget (default 300)
      --max-cost <MAX_COST_USD>    Maximum spend in USD
      --fold-budget <FOLD_BUDGET>  Approximate token budget for the verbatim tail before folding
      --sandbox <SANDBOX>          Sandbox local command execution: 'on' or 'off' (default 'on') [default: on] [possible values: on, off]
      --network <NETWORK>          Outbound network mode: 'on' or 'off' (default 'on') [possible values: on, off]
      --allow-read <ALLOW_READ>    Let sandboxed commands read this path despite credential deny-list (repeatable)
      --no-path-check              Start even if the task names paths outside the workspace and --allow-read
      --no-brief-check             Research runs: no warning for missing brief sections, and allow a question that names an unverified report
      --no-claim-check             Skip the model claim check on report.md for research runs
      --pass-env <PASS_ENV>        Pass this environment variable to commands (repeatable)
  -h, --help                       Print help

The task file is optional when --plan and --plan-task are provided, which take the task directly from the plan.

When blyte dispatch uses the gate from blyte.toml (not an explicit --gate or --research), it checks whether check commands run by the repository's CI workflows (.github/workflows/*.yml and *.yaml) are missing from the gate.

Steps are matched by tool after stripping command wrappers (env, xargs, uv run, uvx, poetry run, pipenv run, pdm run, npx, pnpm exec, bunx, python -m). Commands are matched against check keys: make <target>, cargo <subcmd>, go <subcmd>, npm run <script> / npm test, pnpm run <script> / pnpm test, yarn <script>, ruff <subcmd>, or tool names (pytest, pre-commit, pyright, mypy, eslint, vitest, jest, tsc, tox, nox, black, isort). Equivalent npm, pnpm, and yarn scripts match one another.

A CI step counts as covered when: 1. A gate command has the same check key. 2. Any comment line in blyte.toml contains the step's check key text. 3. The tool's project file is missing at the repository root (Cargo.toml, go.mod, package.json, Makefile, .pre-commit-config.yaml, or Python project files).

The gate-drift warning never fails a dispatch. When uncovered steps exist, it prints a single line to stderr and continues normally:

blyte: the gate is missing CI steps: make typecheck (run blyte init --force to refresh blyte.toml)

blyte review#

Show what a dispatched run did: commits, files, tree state, report, and optionally the diff

Usage: blyte review [OPTIONS] <ID>

Arguments:
  <ID>  

Options:
      --diff               
      --verdict <VERDICT>  [possible values: accepted, fixed, redone]
      --notes <TEXT>       
      --model-review       Ask the implementer model for a first review of the diff against the task (trial)
  -h, --help               Print help

blyte clean#

Remove finished worktrees and merged branches

Usage: blyte clean [OPTIONS]

Options:
      --dry-run            Show what would be removed without deleting anything
      --older-than <DAYS>  Worktrees older than this many days are removable without a verdict (default 14) [default: 14]
      --all                Clean every repository in the registry
  -h, --help               Print help

A run's worktree is removed once its work is merged or discarded. blyte clean reports each worktree with a reason text:

Removable: - merged: work is on the default branch (or origin/<default>). - merged into <base>: work is on the branch the run was dispatched from. - merged through <child>: work is merged through a follow-up run. - <branch> merged: a session worktree under .wt/<name> or .claude/worktrees/<name> whose branch is merged, clean, holds no runs, is not in use, and has been idle for more than 7 days. - verdict redone: the run was discarded with a redone verdict. - no changes: the run completed with outcome no_changes. - research report: a research run whose report was copied to .wt/<id>.report.md. - finished over N days ago: the run finished more than the allowed age in days (default 14).

Kept: - not merged yet: has an accepted or fixed verdict, or is a session worktree whose branch is not yet merged. - uncommitted changes: the worktree has uncommitted modifications or untracked files. - running: the run's process is still alive. - no report: a research run with no report file yet. - in use by a running process: a running process has its working directory inside the session worktree. - used in the last 7 days: the session worktree's git index or HEAD was modified within the last 7 days. - holds runs: review them from <path>: the session worktree contains dispatched runs under <worktree>/.wt/*.start.json.

Worktrees outside the repository whose branch is merged and working directory is clean are reported with their git worktree remove commands, but never deleted automatically.

blyte skill install#

Install the Claude Code skill

Usage: blyte skill install [OPTIONS]

Options:
      --project            Install to repository instead of personal ~/.claude
      --force              Overwrite even if existing skill was modified
      --no-default         Install the skill without making blyte the default in CLAUDE.md
      --no-statusline      Do not set Claude Code's status line
      --no-autocompact     Do not set Claude Code's auto-compact window
      --harness <HARNESS>  Which orchestrator to set up: claude (Claude Code), codex (Codex CLI) or all [default: claude] [possible values: claude, codex, all]
      --model <ID>         Default implementer model to write to the env file
  -h, --help               Print help

If an older, separate blyte-research skill directory exists (~/.claude/skills/blyte-research, ~/.codex/skills/blyte-research, or ~/.agents/skills/blyte-research), blyte skill install warns on stderr that it is superseded by the blyte-implementer skill's research section (default 300 turns) and should be removed (rm -r <path>).

blyte skill uninstall#

Remove the skill and the CLAUDE.md block

Usage: blyte skill uninstall [OPTIONS]

Options:
      --project            Remove from repository instead of personal ~/.claude
      --harness <HARNESS>  Which orchestrator to set up: claude (Claude Code), codex (Codex CLI) or all [default: claude] [possible values: claude, codex, all]
  -h, --help               Print help

blyte update#

Replace this binary with the latest release (the old one is kept as blyte.prev)

Usage: blyte update [OPTIONS]

Options:
      --check     Only show the installed and latest versions
      --rollback  Swap back to the previous build (blyte.prev)
  -h, --help      Print help

It downloads this machine's binary from the latest GitHub release through the GitHub CLI (gh, signed in with access to the repository), checks that it runs, keeps the old binary beside it as blyte.prev, and refreshes every unedited copy of the skill it installed (for Claude Code and Codex). Like blyte skill install, it also checks for a superseded blyte-research skill directory and warns on stderr to remove it.

blyte status#

Show what a dispatch is doing

Usage: blyte status [OPTIONS] <ID>

Arguments:
  <ID>  

Options:
      --json  
  -h, --help  Print help

blyte wait#

Wait until dispatched runs finish (all of them, or the first with --any) and print one line per finished run

Usage: blyte wait [OPTIONS] <IDS>...

Arguments:
  <IDS>...  Run ids, as given to `blyte dispatch`

Options:
      --any                Return as soon as at least one run has finished
      --timeout <TIMEOUT>  Give up after this many seconds (exit 2); stays under the 300 s shell-command limit [default: 280]
  -h, --help               Print help

blyte plan#

List a plan's tasks with their state and the command to dispatch each ready one

Usage: blyte plan [OPTIONS] <PLAN>

Arguments:
  <PLAN>  Path to the plan markdown file

Options:
      --json  Output task statuses as JSON
  -h, --help  Print help

blyte cost#

Show orchestrator and implementer costs

Usage: blyte cost [OPTIONS]

Options:
      --session <ID>       Session identifier to filter by
      --since <UNIX_SECS>  Filter runs at or after this Unix timestamp in seconds
      --repo <PATH>        Repository path to filter by
      --json               Output totals as JSON
  -h, --help               Print help

blyte statusline#

Print Claude Code's status line with blyte costs

Usage: blyte statusline [OPTIONS]

Options:
      --after <COMMAND>  Command to generate the base line before appending blyte costs
  -h, --help             Print help

blyte skill print#

Print the skill markdown to stdout

Usage: blyte skill print

Options:
  -h, --help  Print help

Environment#

variable meaning
BLYTE_MODEL default for --model
GEMINI_API_KEY, ANTHROPIC_API_KEY, OPENAI_API_KEY, OPENAI_BASE_URL, OPENROUTER_API_KEY, OLLAMA_HOST, OLLAMA_API_KEY provider credentials and endpoints; never passed to commands
GOOGLE_CLOUD_PROJECT, CLOUDSDK_CORE_PROJECT, GOOGLE_CLOUD_LOCATION project and location for Vertex AI models (vertex/<model>); never passed to commands
CODEX_HOME where the ChatGPT provider looks for auth.json (default ~/.codex)
GOOGLE_API_KEY read for Gemini when GEMINI_API_KEY is not set; never passed to commands
BLYTE_ENV_FILE the file provider keys are loaded from (default ~/.config/blyte/env); empty turns loading off
BLYTE_MODEL_TIMEOUT_SECS limit for one model call: 180 s by default, 1800 s for a streamed Gemini call
BLYTE_MODEL_IDLE_TIMEOUT_SECS how long a streamed Gemini call may stay silent before it fails (default 300 s)
BLYTE_GEMINI_THOUGHT_SUMMARIES 0 turns off Gemini's thought summaries
BLYTE_GATE_SLOTS how many gates may run at once on the machine (default a quarter of the cores, at least 2)
BLYTE_STATE_DIR where blyte keeps its state, such as the list of repositories the dashboard reads (default $XDG_STATE_HOME/blyte or ~/.local/state/blyte)
BLYTE_NO_UPDATE_CHECK 1 turns off the check for a newer release

Models prefixed with vertex/ (such as vertex/gemini-4-argon) reach Gemini through Vertex AI using Google Cloud Application Default Credentials instead of an API key. Authenticate by running gcloud auth application-default login. The cloud project is read from GOOGLE_CLOUD_PROJECT (or CLOUDSDK_CORE_PROJECT), and the location from GOOGLE_CLOUD_LOCATION (default global).