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 services, write config |
| ace config | Print effective configuration |
| ace config get <key> | Read one value. Keys: school, backend, trust, resume, session_prompt, skip_update, and env.KEY. |
| ace config explain [<key>] | Show every configured layer, optionally narrowed to one readable key, and explain which value wins. |
| ace config set <key> <value> | Write a value. 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 |
| ace pull | Fetch latest school changes (force, ignoring cooldown). 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 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 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 cache. 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 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 MCP server, then re-add with ace mcp register. Mass-only — it takes no name. |
trust
| Command | Description |
|---|
| ace auto | Request the backend's auto trust behavior; support and exact permission flags vary by backend |
| ace yolo | Request 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 logo. |
| --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 any registered backend. Built-in shortcuts are --claude, --codex, and --opencode. |
| --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 |