CLI reference
agnostic-ai [command] [flags]
Run project commands from the folder containing agnostic-ai.yaml, unless the command documents support for subdirectories or --global. Use agnostic-ai <command> --help for the options available in your installed release.
To troubleshoot, start with doctor and follow its next step, or see troubleshooting by symptom.
Find a command
Root help groups commands into setup, daily generation, diagnosis and inspection, and maintenance. A fresh project can follow this path:
echo "claude,codex" | agnostic-ai init
agnostic-ai sync --plan
agnostic-ai sync
agnostic-ai doctor
| Task | Commands |
|---|---|
| Set up a project | use, init, import, new |
| Generate or preview output | sync, render |
| Diagnose problems, then check a specific area | doctor, validate, lint, status, verify |
| Find which specs each tool reads | list, explain, compare, graph, why |
| Inspect tool permissions and settings | ui / view, serve |
| List each MCP server's tools for the overview | mcp tools |
| Restore or remove generated files | revert, cleanup |
| Share specs | packs |
| Check and maintain shared memory | memory commands |
| Write and test hook commands | hook paths, hook run, hook worktree-remove |
| Check or prepare the project CLI | project, readiness checks |
| Set up your environment | completion, upgrade or update, migrate, install-hook, lsp |
Walkthroughs: Getting started, Migration. Automation: exit codes, CI guide.
Concurrent commands
sync (including --watch, until it exits), import, use, init, and migrate hold one project lock while they run. A second writer exits with the running command's name and process ID; retry after it finishes. sync --check, sync --plan, dry runs, status, list, and global commands take no lock. The lock works between processes on one machine, not across a network file system.
The lock file, .agnostic-ai/.command-lock, stays on disk; leave it. The managed .gitignore block ignores it, and writing commands refresh those runtime entries even when generated outputs are committed. The operating system releases the lock when the process exits or is killed.
Global flags
| Flag | Description |
|---|---|
-h, --help | Help for any command, same as agnostic-ai help <command>. |
--version | Print the version and exit |
-q, --quiet | Errors only, plus the ~ kept lines of sync --keep-edits, on stderr |
-v, --verbose | Increase output verbosity (repeatable). Mutually exclusive with --quiet. |
--profile <file> | Write a runtime/pprof CPU profile to <file> (or set AGNOSTIC_AI_PROFILE). Read it with go tool pprof <file>. |
Exit codes
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Any error (invalid file format, file read or write failure, missing config) |
| verifier exit code | verify returns the external verifier's non-zero code unchanged. |
Environment variables
| Var | Default | Description |
|---|---|---|
AGNOSTIC_AI_HOME | ~/.agnostic-ai | Source folder for sync --global, list --global, lint --global, validate --global, and migrate --global, including their local/ override layer. Project sync does not load it. See global configuration. |
Which config wins
See which value wins in the configuration reference.