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) |
| ace link | Re-link school folders into the project (no pull) |
| ace version | Print version information (also ace --version / -V) |
| ace learn | Study the project and narrow it down. Edits the backend instructions file (CLAUDE.md, AGENTS.md, …) in place with project-specific notes and rewrites ace.toml's skills to the relevant subset. Auto-offered by ace setup, ace school pull, and ace startup when the school exposes more than 10 skills. Review with git diff. |
| 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 a skill from an external repository. --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. --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
| Command | Description |
|---|
| ace mcp | Per-entry prompt to register each missing school-defined MCP server. Declining a server appends its name to exclude_mcp in ace.local.toml; subsequent runs silently skip it. Bare ace uses the same flow on first-run startup. |
| ace mcp register <name> | Un-skip a previously declined server: removes <name> from exclude_mcp in ace.local.toml and registers it. OAuth-only entries print backend-specific setup instructions. Errors if <name> isn't declared in the active school. |
| ace mcp check | Health-check registered MCP servers (read-only) |
| ace mcp reset [name] | Remove registered MCP servers, then re-add with ace mcp |
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.
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 $?.