CLI reference

bacio's CLI is the same surface that agents drive — every mutating command accepts JSON via --json, every payload schema is reachable at runtime via bacio schema, and every mutation supports --dry-run. See agent-CLI principles for the design rules behind that.

Top-level commands

Command	What it does
bacio init	Bind the current git repo to a 4-letter prefix.
bacio repo	List, show, or remove tracked repos.
bacio feature	Manage features (groups of issues). Includes plan for dependency-ordered execution.
bacio issue	Manage issues — add, list, show, brief, edit, state, assign, unassign, next, peek, rm.
bacio comment	Add and list issue comments.
bacio link / bacio unlink	Create / remove typed issue relations (blocks, relates-to, duplicate-of — stored as blocks, relates_to, duplicate_of).
bacio pr	Attach, detach, and list pull requests on an issue.
bacio tag	Add or remove tags on issues.
bacio doc	Manage per-repo text documents and their links to issues / features.
bacio agent	Track live AI-agent sessions and their issue claims (local-only registry).
bacio status	One-screen summary of the current repo.
bacio history	Query the audit log of mutations.
bacio schema	List and show JSON schemas for every --json payload.
bacio sync	Mirror the SQLite DB to a git-backed YAML+markdown repo.
bacio api	Run the REST API server.
bacio install-skill	Install the canonical SKILL.md for AI agents into the repo.
bacio install-sample-skills	Install the bundled flow-level skill packs (file-issue, triage, stand-up, plan-feature).
bacio tui	Open the full-screen kanban TUI.

Global flags

All commands inherit these from the root:

Flag	Default	What it does
-o, --output	text	Output format — text for humans, json for agents and scripts.
--db	~/.bacio/db.sqlite	Override the database path. Useful for tests and isolated experiments.
--user	OS user	Actor name recorded in history. AI agents should pass this explicitly.
--dry-run	off	Validate the request and emit the projected result without writing. No audit log entry.
--remote	—	Talk to a bacio api server at this URL instead of the local DB. Falls back to BACIO_REMOTE.
--token	—	Bearer token for the remote API. Falls back to BACIO_API_TOKEN.

Conventions

• JSON in via --json. Mutating commands accept --json <inline>, --json - (stdin), or --json @path/to.json (file). Mutually exclusive with positional and per-field flags.
• Lean lists, fat shows. *.list strips heavy bodies; *.show and bacio issue brief return full records.
• Strict decode. Unknown JSON fields are rejected, not silently dropped.
• Audit log. Every mutation records who, when, and what changed. Pruned to 60 days on every DB open.