commands
Every ACE command, grouped by what it touches — core workflow, skills, school
management, MCP, trust, and updates.
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, env.KEY. |
| ace config set <key> <value> | Write a value. Layer inferred from the key; override with --user / --project / --local. |
| 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 |
| 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 provenance and per-step trace for one skill (which scope/field decided its inclusion). |
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 | Enable auto trust mode (AI decides which actions need approval) |
| ace yolo | Enable yolo trust mode (skip all permission prompts) |
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) |
Pass --porcelain for machine-readable output — no colors, no
spinners, no logo.
For unattended runs, --yes / -y answers
every checklist with its default instead of asking; a prompt with no default — free-form
and single-choice — fails rather than guesses. A set CI
environment variable implies it.
Run the backend non-interactively with -p /
--prompt <text>: it answers that one prompt and exits, translated
to each backend's native form. Add or override environment variables per invocation with
repeatable --env KEY=VAL.
Temporarily override backend selection with -b <name> /
--backend <name> for any registered backend
(claude, codex, opencode, custom),
or use the --claude / --codex / --opencode shortcuts.
Scope writes with --user, --project, or --local.
Pass flags to the backend with ace -- --flag.
On failure ace returns a distinct exit code per class —
usage (1), unavailable (2), operational (3), cancelled (130) — so wrappers can branch on $?.