CLI Reference

Every command below was verified against the installed assync CLI (assync --help and each subcommand's --help) before publishing this page. Commands under mission, project, role, run, finding, synthesis, decision, audit, and lock require running from inside (or below) a directory that contains .assync/ — see assync init.

Top-level

assync [OPTIONS] COMMAND [ARGS]...

Command	Purpose
init	Initialize Assync in a repository (scaffolds .assync/).
status	Show the Assync Brain Console status.
sync	Sync the Assync Brain with the remote (fetch + fast-forward pull).
validate	Run health checks and validate the Assync Brain.
handoff	Manage Assync handoffs.
mission	Manage mission-orchestrator missions.
project	Manage the external Assync project registry.
role	Inspect the built-in role pool.
run	Inspect agent runs.
finding	Inspect findings.
synthesis	Inspect and rebuild mission synthesis.
decision	Manage the human decision queue.
audit	Inspect the append-only audit log.
lock	Inspect and (explicitly) clear mission locks.

assync init

assync init [path]

Initializes Assync in path (default .), scaffolding .assync/ (manifest.yaml, boot.md, rules.md, current-state.md, missions/, decisions/, handoffs/, reports/, templates/, events/).

assync project

Command	Required options	Notes
project register	--name, --repository-path	--repository-type (default consumer), --require-git/--no-require-git (default: require).
project list	—	--json for machine-readable output.
project show {project_id}	—

assync role

Command	Options	Notes
role list	--category	Lists all built-in roles. See Built-in Roles.
role show {role_id}	—
role validate	—	Validates the built-in role registry against the rules in Role Pool.

assync mission

Command	Required options	Other options
mission create	--project-id, --title, --objective	--authorization-type (default IMPLEMENTATION_GO), --required-role (repeatable), --acceptance-criterion (repeatable), --risk-level (default medium), --file (YAML/JSON mission definition, overrides other options).
mission list	—	--json.
mission show {mission_id}	—
mission status {mission_id}	—
mission start {mission_id}	--run-config	--actor (default cli-operator). --run-config points to a JSON file: {role_id: {adapter, scenario|argv...}}.
mission abort {mission_id}	--reason	--actor (default cli-operator).

assync run

Command	Options
run list	--mission-id, --json
run show {run_id}	—

assync finding

Command	Options
finding list	--mission-id
finding show {finding_id}	—

assync synthesis

Command	Notes
synthesis show {mission_id}	Prints the current SynthesisResult.
synthesis rebuild {mission_id}	Recomputes synthesis from current runs/findings/evidence without re-executing any run — useful after a finding's risk is accepted.

assync decision

Command	Required options	Other options
decision list	—	--mission-id
decision show {decision_id}	—
decision approve {decision_id}	--actor	--option-id (default approve), --rationale
decision reject {decision_id}	--actor	--option-id (default reject), --rationale
decision request-changes {decision_id}	--actor	--option-id (default request_changes), --rationale

Every resolution command requires an explicit --actor — there is no "resolve as system" path. See Decision Queue.

assync audit

Command	Options
audit show	--mission-id, --json

assync lock

Command	Options	Notes
lock show {mission_id}	—
lock clear {mission_id}	--force (required)	An explicit, non-recoverable override — a lock is never silently stolen.

assync handoff

Command	Notes
handoff latest	Reads and displays the latest handoff report.
handoff create {agent} {mission}	Creates a new handoff report and updates latest.yaml.

Exit codes

See Exit Codes — every command shares one stable exit-code contract (commands/_common.py).