CLI reference

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
`belai agent`	Agents and agent profiles
`belai`
`belai budget`	The library: skills, prompts, commands, processes, repos and more
`belai command`	The library: skills, prompts, commands, processes, repos and more
`belai crew`	Crews
`belai kanban`	The board
`belai library`	The library: skills, prompts, commands, processes, repos and more
`belai login`	Install, update and sign in
`belai mcp`	The library: skills, prompts, commands, processes, repos and more
`belai plugin`	Plugins
`belai process`	The library: skills, prompts, commands, processes, repos and more
`belai prompt`	The library: skills, prompts, commands, processes, repos and more
`belai provider`	The library: skills, prompts, commands, processes, repos and more
`belai rc`	Remote control and connected hosts
`belai repo`	The library: skills, prompts, commands, processes, repos and more
`belai rewrite`	The library: skills, prompts, commands, processes, repos and more
`belai skill`	The library: skills, prompts, commands, processes, repos and more

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/ 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

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