commands
ACE commands grouped by what they touch — core workflow, skills, school management,
MCP, trust, and updates — followed by shared options and exit codes.
core
| Command | Description |
|---|
| ace | Launch the configured AI backend |
| ace setup [<spec>] | Clone a school, authenticate, write config. Reuses existing Git credentials or offers token entry in a terminal. Omit <spec> to link a cached school. |
| ace config | Print the effective configuration as one TOML document |
| ace config get <key> | Read one resolved value. Keys: school, backend, trust, resume, skip_update, session_prompt, env.KEY, backends.NAME.model, and backends.NAME.effort (NAME is a built-in or custom backend instance); read-only: skills, include_skills, exclude_skills, exclude_mcp. |
| ace config explain [<key>] | Show every configured layer, optionally narrowed to one key (the same keys as get, read-only ones included), and explain which value wins. |
| ace config set <key> <value> | Write a value. Accepts the get keys, including backends.NAME.model and backends.NAME.effort; rejects the read-only selection fields skills, include_skills, exclude_skills, and exclude_mcp. The default and available scopes depend on the key; trust and resume are personal settings and do not support project scope. |
| ace paths [<key>] | Print resolved filesystem paths, or one key such as project, cache, school, or worktrees |
| ace pull [<spec>] | Clone or update any school as an ACE-managed clone (force, ignoring cooldown). Bare ace pull updates the linked school. Points you at ace link when the pull changed which skills resolve. |
| ace link [--force] | Re-link school folders into the project (no pull). --force replaces symlinks left behind by a previous school. |
| ace version | Print version information (also ace --version / -V) |
| ace new | Start a fresh backend session (skip auto-resume) |
| ace llm-help | Print the capability catalog for AI agents: features, where each lives, and what is out of scope. It ships with the binary and matches its version. |
| ace fmt | Format ace.toml / school.toml (pretty-print, strip empties) |
| ace format | Alias for ace fmt |
skills
| Command | Description |
|---|
| ace import <source> | Import skills from an external repository — <source> is any git URL or an owner/repo shorthand. Picks several skills at once and merges them into the existing skills declaration. --skill NAME picks a specific skill (or glob pattern) across all tiers, --all bulk-imports curated skills. Add --include-experimental / --include-system to expand --all into those tiers. |
| ace diff | Show uncommitted changes in the school clone. Long terminal output opens in $PAGER; pipes and --porcelain keep the plain stream. |
| ace skills [--all] [--names] | List resolved skills with tier and status (alias: ace ls). --all includes excluded skills; --names prints bare names, one per line. |
| ace skills include <pattern>... | Append skill names or glob patterns to include_skills. Defaults to project scope; pass --user or --local to target another layer. |
| ace skills exclude <pattern>... | Append patterns to exclude_skills. Same scope flags as include. |
| ace skills reset [--include] [--exclude] | Reset include_skills and/or exclude_skills to empty. Bare reset clears both. |
| ace explain <name> | Show a skill's description, provenance, and per-step resolution trace. |
school management
| Command | Description |
|---|
| ace school init [--name N] [--force] | Initialize a new school repository. --name sets the display name (otherwise inferred from the directory). --force overwrites an existing school.toml. |
| ace school pull | Re-fetch all imported skills from sources (alias: ace school update) |
| ace school skills | List skills in the school |
| ace school validate | Validate school.toml (typo-check {{ ... }} placeholders). Alias: ace school check. |
mcp
Bare ace prompts per entry on first-run startup to register each
missing school-defined server; declining one appends its name to
exclude_mcp in ace.local.toml and later
runs skip it silently. The ace mcp subcommands below never prompt.
| Command | Description |
|---|
| ace mcp | List registered MCP servers. Read-only — it registers nothing and prompts for nothing. |
| ace mcp register <name> | Register one school-defined server. Un-skips a previously declined one by removing <name> from exclude_mcp in ace.local.toml. OAuth-only entries print backend-specific setup instructions. Errors if <name> isn't declared in the linked school. |
| ace mcp unregister <name> | Remove one registered server. Alias: ace mcp remove. |
| ace mcp check | Health-check registered MCP servers (read-only) |
| ace mcp reset | Remove every registered school-defined MCP server, then re-add with ace mcp register. Mass-only — it takes no name. |
trust
| Command | Description |
|---|
| ace auto | Persist auto trust mode (the AI decides which actions need approval). Requests the backend's auto trust behavior; support and exact permission flags vary by backend |
| ace yolo | Persist yolo trust mode (skip all permission prompts). Requests the backend's least-restrictive trust behavior; support and exact permission flags vary by backend |
updates
ACE checks for newer releases on every invocation and silently upgrades in the background.
Disable with skip_update = true or ACE_SKIP_UPDATE=1.
| Command | Description |
|---|
| ace upgrade | Check for a newer release within the current major and upgrade in place |
| ace upgrade --force | Reinstall even if already at the latest version |
| ace upgrade --force VERSION | Install a specific version (downgrade or cross a major boundary) |
| ace upgrade --silent | Suppress all output (used by the background spawn) |
global options
| Option | Behavior |
|---|
| --porcelain | Use machine-readable output without colors, spinners, or a wordmark. |
| --yes, -y | Answer checklists with their defaults. Prompts without defaults fail rather than guess; a set CI environment variable implies this mode. |
| --prompt <text>, -p <text> | Run the backend for one noninteractive prompt, translated to the backend's native form, then exit. |
| --env KEY=VAL | Add or override an environment variable for this invocation. Repeat for multiple values. |
| --backend <name>, -b <name> | Temporarily select a backend: a built-in (claude, codex, opencode, pi) or a name declared under [backends.<name>]. Built-in shortcuts are --claude, --codex, --opencode, and --pi. |
| --trust <mode> | Set the trust mode (default, auto, or yolo) for this invocation only; nothing is written to disk. Shortcuts: --auto, --yolo. Use ace auto / ace yolo to persist. |
| --session-prompt <text> | Use an inline session prompt for this invocation only. |
| --user / --project / --local | Choose the configuration layer for a write when that key supports the scope. |
| -- <backend flags> | Pass the remaining flags directly to the backend. |
exit codes
Wrappers can branch on $? using ACE's failure classes.
| Code | Meaning |
|---|
| 1 | Usage error |
| 2 | Requested operation unavailable |
| 3 | Operational failure |
| 130 | Cancelled |