# CLI reference

Every belai command, subcommand and flag: 162 flags across 18 commands.

Every `belai` command, subcommand and flag. Flags take one dash or two (`-json` and `--json` are the same). Run `belai <command> -help` for the same list on your machine.

## Commands

| Command | Explained in |
|---|---|
| `belai acp` | [Editors over ACP](/software-factory/belai/editors-acp.md) |
| `belai agent` | [Agents and agent profiles](/software-factory/workforce/agents.md) |
| `belai` |  |
| `belai budget` | [The library: skills, prompts, commands, processes, repos and more](/software-factory/workforce/library.md) |
| `belai command` | [The library: skills, prompts, commands, processes, repos and more](/software-factory/workforce/library.md) |
| `belai crew` | [Crews](/software-factory/workforce/crews.md) |
| `belai kanban` | [The board](/software-factory/workforce/board.md) |
| `belai library` | [The library: skills, prompts, commands, processes, repos and more](/software-factory/workforce/library.md) |
| `belai login` | [Install, update and sign in](/software-factory/belai/install-and-sign-in.md) |
| `belai mcp` | [The library: skills, prompts, commands, processes, repos and more](/software-factory/workforce/library.md) |
| `belai plugin` | [Plugins](/software-factory/belai/plugins.md) |
| `belai process` | [The library: skills, prompts, commands, processes, repos and more](/software-factory/workforce/library.md) |
| `belai prompt` | [The library: skills, prompts, commands, processes, repos and more](/software-factory/workforce/library.md) |
| `belai provider` | [The library: skills, prompts, commands, processes, repos and more](/software-factory/workforce/library.md) |
| `belai rc` | [Remote control and connected hosts](/software-factory/workforce/remote-control.md) |
| `belai repo` | [The library: skills, prompts, commands, processes, repos and more](/software-factory/workforce/library.md) |
| `belai rewrite` | [The library: skills, prompts, commands, processes, repos and more](/software-factory/workforce/library.md) |
| `belai skill` | [The library: skills, prompts, commands, processes, repos and more](/software-factory/workforce/library.md) |

## Subcommands

### agent

`control`, `crew`, `crew delete`, `crew export`, `crew import`, `crews`, `draft`, `files`, `import`, `knowledge`, `list`, `logs`, `memory`, `pause`, `ps`, `resume`, `run`, `runs`, `show`, `start`, `status`, `stop`, `supervise`, `validate`

### kanban

`add`, `assign`, `checkpoint`, `delete`, `import`, `list`, `move`, `note`, `release`, `show`

### kanbanassign

`none`

### lib

`export`, `import`, `list`, `validate`

### plugin

`disable`, `enable`, `install`, `list`, `remove`, `update`

### repo

`list`, `status`, `sync`

## Flags

### belai (top level)

| Flag | Default | What it does |
|---|---|---|
| `-agent` |  | start a background agent by name in foreground mode |
| `-agent-create` |  | create an agent profile from a description and save to disk |
| `-allow-ask-without-tty` |  | ignore ask-without-tty blocks |
| `-allow-invalid-hooks` |  | ignore invalid hook validation |
| `-allow-invalid-skills` |  | ignore invalid skill validation |
| `-allow-malformed-prompt` |  | ignore malformed prompt classification |
| `-allow-malformed-tool-result` |  | ignore malformed tool results |
| `-allow-unpermitted-tools` |  | allow tool calls matching no permission rule (default) |
| `-allow-unsafe-prompt` |  | ignore unsafe prompt classification |
| `-allow-unsafe-tool-result` |  | ignore unsafe tool results |
| `-answers` |  | with -prompt, answer the questions the run asks (a goal's clarification round, AskUserQuestion, a stuck goal) from this JSON file of your answers, in order; without it the run asks nothing |
| `-as` |  | the path the profile lists for the file (default: the file's name) |
| `-ask-permission` | `true` | enable the permission-ask gate; -ask-permission=false resolves asks to allow |
| `-auto` |  | hand the model back to the crew's pool |
| `-c` |  | shorthand for -continue |
| `-caveman` |  | enable caveman voice rewrite for this run |
| `-claim` |  | with -prompt, what to claim: LIST[:LABEL,LABEL] (default: backlog) |
| `-classifier-effort` |  | security-classifier thinking effort (default: none) |
| `-classifier-kind` |  | security-classifier stack: llm, models, openrouter-decisions or systemone (jev is read as systemone) (default: models when the binary embeds a model, else llm) |
| `-classifier-model` |  | security-classifier model (default: the main model) |
| `-classifier-phase1-model` |  | phase-1 prompt-saturation model id |
| `-classifier-phase1-source` |  | phase-1 source: embedded or huggingface |
| `-classifier-phase1-threshold` |  | phase-1 attack threshold (default 0.75) |
| `-classifier-phase2-model` |  | phase-2 jailbreak model id |
| `-classifier-phase2-source` |  | phase-2 source: embedded, huggingface, or disabled |
| `-classifier-phase2-threshold` |  | phase-2 attack threshold (default 0.75) |
| `-classifier-provider` |  | security-classifier provider (default: the main provider) |
| `-continue` |  | continue the most recent session for this project |
| `-dangerously-yolo-everything` |  | ignore every posture gate |
| `-defer-tools` | `true` | advertise core tools in full and load the rest on demand with ToolSearch; -defer-tools=false sends every tool definition on every request |
| `-detect-mode` |  | run the operating-mode classifier and report the decision |
| `-drain` |  | finish the card in hand, then stop |
| `-dry-run` |  | say what would be attached without doing it |
| `-effort` |  | the effort of the next turn |
| `-export` |  | export a session by id or unique id prefix as Markdown and exit |
| `-firewall` |  | route LLM traffic through the active AI Firewall (see /firewall) |
| `-force` |  | replace an existing crew of the same name |
| `-guardrails` | `true` | enable the posture guardrails; -guardrails=false is the guardrails-off half of YOLO |
| `-index` |  | bring the indexes up to date first (classifies new text) |
| `-json` |  | print JSON |
| `-mode` |  | operating mode for -prompt: agent, plan, goal or code (default: classified from the prompt) |
| `-model` |  | model override |
| `-no-git-sync` |  | do not rebase the branch onto origin's default branch before a turn (git.sync in settings; /gitsync in the TUI) |
| `-no-prune` |  | never prune idle sessions |
| `-no-transcript` |  | with -prompt, do not keep a session transcript of the run |
| `-o` |  | write the markdown to FILE instead of stdout |
| `-plan` |  | start in plan mode (read-only) |
| `-prompt` |  | run a worker made from this prompt instead of a stored profile |
| `-provider` |  | provider override |
| `-publish` |  | with -prompt, none, draft_pr or agent (default: agent) |
| `-r` |  | shorthand for -resume |
| `-read-only` |  | with -prompt, run checks in a throwaway worktree and change nothing |
| `-resume` |  | resume a session by id or unique id prefix |
| `-run` |  | the crew run to supervise |
| `-session-retention-days` |  | idle session retention in days (default 28) |
| `-teleport` |  | continue a session of your account from another host, sandbox or the web: its transcript and any agent profile it needs are fetched, and the session opens here under a new id (the original carries on) |
| `-teleport-push` |  | with -teleport, agree that the origin host may push the session's uncommitted and unpushed changes to the forge as one belai/teleport/<id> branch, which this host then fetches; without it they are sent as a patch and replayed here |
| `-teleport-ref` |  | with -teleport, check out this ref or commit instead of the one the session was at |
| `-to` |  | with -prompt, the list a success goes to (default: review, or done for a worker that only decides) |
| `-tool-call-mismatch` |  | abort\|strip\|ignore tool-call mismatches |
| `-tools` |  | with -prompt, the tools the worker may use, comma separated (default: all) |
| `-trust-dir` |  | trust the repository first |
| `-usage-json` |  | with -prompt, write a JSON summary of the run's token usage (per role, per model, request composition) to this path on exit |
| `-verbose` |  | print role-manager decisions to stderr |
| `-version` |  | print version and exit |

### belai acp

| Flag | Default | What it does |
|---|---|---|
| `-model` |  | model id (default: the provider's) |
| `-no-transcript` |  | do not keep a session transcript of editor sessions |
| `-provider` |  | provider (default: as for the TUI) |

### belai agent

| Flag | Default | What it does |
|---|---|---|
| `-all` |  | include ended crew runs |
| `-ask-off` |  | a call that would ask is allowed instead of blocking the item (set by `agent start -ask-off`) |
| `-clear` |  | delete the lessons |
| `-crew` |  | the crew this worker belongs to (set by `agent start`) |
| `-detached` |  | started by `agent start` |
| `-dir` |  | with -crew, a directory in the crew's scope, PATH or PATH:WEIGHT (repeatable; default this repository) |
| `-drain` |  | exit once nothing is left to claim even when the profile has a cron schedule |
| `-effort` |  | effort override (set by the crew supervisor) |
| `-f` |  | follow |
| `-fill` |  | with -crew, confirm a crew already running over this directory instead of refusing (its supervisor keeps it full) |
| `-final-retry` |  | with -crew, seconds the crew sleeps once the whole pool failed, before its final retry (default 900) |
| `-force` |  | replace an existing profile of the same name |
| `-from` |  | the format of a definition written for another harness: claws, nemoclaw, hermes, mini-swe or auto |
| `-id` |  | worker id (set by `agent start`) |
| `-item` |  | work this item |
| `-json` |  | print JSON |
| `-max-workers` |  | worker cap to reserve under in place of agents.max_workers (set by `agent start`) |
| `-model` |  | model override |
| `-n` | `40` | lines from the end |
| `-name` |  | with -from: the profile name to use instead of the one in the source |
| `-once` |  | work one item (or find none) and exit |
| `-pool` |  | with -crew, a provider/model in the crew's pool, which workers cycle when one keeps failing (repeatable) |
| `-provider` |  | provider override |
| `-replicas` | `1` | workers of the profile |
| `-run` |  | the crew run this worker belongs to (set by the crew supervisor) |
| `-stay` |  | keep waiting for work instead of exiting once nothing is left to claim |
| `-stay-idle-max` |  | with -stay, exit after this long with nothing to claim (default 6h, at most 24h) |
| `-switch-after` |  | with -crew, outages in a row before a worker moves to the next target in the pool (default 3) |
| `-trust-dir` |  | trust the repository first |
| `-web-allow-guardrails-off` |  | with -web-controls, guardrails may be turned off from the website (set by `agent start`) |
| `-web-controls` |  | take session controls from the website (set by `agent start`) |
| `-yes` |  | with -from: save the profile and install its skills (without it the import is a preview) |

### belai crew log

| Flag | Default | What it does |
|---|---|---|
| `-audit` |  | print audit entries instead of faults |
| `-class` |  | only faults of this class |
| `-crew` |  | the newest run of this crew |
| `-follow` |  | keep printing new lines |
| `-json` |  | print JSON lines |
| `-limit` |  | print at most the newest N lines |
| `-run` |  | the run to read |
| `-verify` |  | check the audit hash chain |
| `-worker` |  | only this worker's lines |

### belai kanban

| Flag | Default | What it does |
|---|---|---|
| `-assignee` |  | agent profile to route to |
| `-body` |  | details |
| `-body-file` |  | read the details from a file |
| `-crew` |  | route to a crew's entry profile |
| `-depends` |  | item that must be done first (repeatable) |
| `-flow` |  | feature, bug or ui: file it for that flow crew's first stage |
| `-host` |  | this, a sync host id, or none |
| `-json` |  | print JSON |
| `-label` |  | routing label (repeatable) |
| `-limit` | `50` | at most this many |
| `-list` | `backlog` | backlog or review |
| `-note` |  | why |
| `-priority` |  | -2 to 3 |
| `-project` |  | project name (default: this directory's) |
| `-start` |  | start the worker or crew in this directory |
| `-to` | `blocked` | list a rejected card goes to |

### belai library scan

| Flag | Default | What it does |
|---|---|---|
| `-json` |  | print JSON |
| `-kind` |  | scan one kind of item |

### belai login kiro

| Flag | Default | What it does |
|---|---|---|
| `-api-region` |  | Kiro API region |
| `-backend` |  | keychain or user-file |
| `-import` |  | import Kiro's own sign-in |
| `-profile-arn` |  | CodeWhisperer profile ARN |
| `-region` |  | SSO region |
| `-start-url` |  | IAM Identity Center start URL |

### belai plugin

| Flag | Default | What it does |
|---|---|---|
| `-yes` |  | install without the interactive confirmation (the listing is still printed) |

### belai rc

| Flag | Default | What it does |
|---|---|---|
| `-allow-private-cidr` |  | let WebFetch reach this private-use range (repeatable); loopback and link-local are never allowed, and every other private address stays refused |
| `-detach` |  | run in the background; logs go to ~/.vulnetix/belai/rc/rc.log |
| `-dir` |  | also offer this directory (repeatable); it is trusted, as with -trust-dir |
| `-idle` | `rc.DefaultIdle` | end a session after this long without a prompt |
| `-max` | `rc.DefaultMax` | sessions to run at once; when given without --max-workers, also the fleet worker cap in place of agents.max_workers |
| `-max-workers` |  | fleet workers to run at once, in place of agents.max_workers; sessions stay capped by --max |
| `-no-clone` |  | never clone a repository a Software Factory request names and this machine does not offer, whatever agents.clone says |
| `-status` |  | show whether remote control is running |
| `-stop` |  | stop the running remote control and its sessions |
| `-web-allow-guardrails-off` |  | with --web-controls, let a web session turn its guardrails off |
| `-web-controls` |  | let web sessions change their mode, model, guardrails, ask and display with the TUI's slash commands and keys (that session only) |
| `-web-project-settings` |  | let the website read and edit each offered directory's project preferences on this host |
| `-web-shell` |  | let web sessions run a shell line on this host, under the TUI's `!cmd` permission rules and OS sandbox |

### belai rc-session

| Flag | Default | What it does |
|---|---|---|
| `-add-dir` |  | an extra workspace directory for the session (repeatable; the daemon checked each is offered) |
| `-allow-guardrails-off` |  | with -controls, a web session may turn guardrails off |
| `-ask` |  | on or off: the start request's permission-ask switch for this session (default: ask_permission in settings) |
| `-controls` |  | take session controls from the web (belai rc --web-controls) |
| `-dispatch` |  | the website request this session answers |
| `-effort` |  | effort for this session (default: the host's own) |
| `-git-sync` |  | on or off: sync the branch with origin's default branch before turns (default: git.sync in settings) |
| `-idle` | `rc.DefaultIdle` | end after this long without a prompt |
| `-mode` |  | agent, plan, goal, code or pix-assistant (default: classified) |
| `-model` |  | model for this session (default: the host's own) |
| `-profile` |  | engage this agent profile for agent-mode turns (a web request's choice, with -mode agent), or the persona of a -mode pix-assistant session |
| `-provider` |  | provider for this session (default: the host's own) |
| `-session-id` |  | the session id the daemon minted |
| `-shell` |  | run shell lines from the web (belai rc --web-shell) |

### belai repo

| Flag | Default | What it does |
|---|---|---|
| `-json` |  | print JSON |
