CLI Reference

CLI Reference

All commands run through the ai-config executable. Running ai-config with no command prints the help text.

ai-config init [--fresh]

Initialize the unified configuration structure under ~/.agents/.

ai-config init           # create config dirs and default files
ai-config init --fresh   # remove existing config and start over

Creates:

• ~/.agents/config/config.json (default unified config)
• ~/.agents/config/mcp-config.json (empty MCP server list)
• ~/.agents/config/AGENTS.md (shared rules file)
• data/, state/, and cache/ directories

--fresh deletes the entire existing ~/.agents/config directory first. Use with care.

ai-config migrate [provider] [--project] [--all-projects]

Migrate existing provider configurations into the unified layout.

ai-config migrate                 # migrate all detected providers
ai-config migrate devin           # migrate one provider
ai-config migrate --project       # migrate the current project's configs
ai-config migrate --all-projects  # scan all projects, move skills to ~/.agents/skills

Behavior:

• Without flags: migrates user-level configs for all detected providers (Devin, Windsurf, Claude, Cursor, Codex, Gemini, VS Code, Copilot CLI, Zed, Continue).
• With a provider name: migrates only that provider. Exits non-zero if the provider is unknown.
• --project: finds the project root (via .git or .ai) and migrates project-level provider configs. Errors if you are not inside a project.
• --all-projects: scans all projects and migrates their skills into the global ~/.agents/skills directory.

Legacy configs are backed up with a .backup extension before changes. See Migration.

ai-config validate

Validate the unified configuration setup. Exits non-zero when issues are found.

ai-config validate

Checks:

• config, data, state, and cache directories exist
• config.json parses and contains shared, providers, context_servers, and skills
• Each configured provider and MCP server is listed
• Skills directory counts */SKILL.md entries
• If inside a project, reports .ai/config.json and .ai/config.local.json presence

ai-config status

Show current configuration status.

ai-config status

Reports directory locations, whether the unified config exists, configured providers, MCP servers, enabled skills, and project detection.

ai-config init-project

Initialize a .ai/ directory in the current project.

cd your-project
ai-config init-project

Requires a git repository (finds the root via .git). Creates:

• .ai/config.json with default permissions and read_config_from flags
• .ai/AGENTS.md for project rules
• .ai/skills/ directory
• .gitignore entries for .ai/config.local.json and .ai/mcp-config.local.json

Does nothing if .ai/ already exists.

ai-config get-config <provider>

Print the effective configuration for a provider as JSON.

ai-config get-config devin

Exits non-zero if the unified config cannot be read.

ai-config sync [--provider NAME] [--project] [--all] [--prune] [--dry-run]

Write the unified config back to each provider's native files. This is the export direction: migrate imports provider configs into ~/.agents/, and sync renders ~/.agents/ back out to native locations.

ai-config sync --dry-run           # preview every write, touch nothing
ai-config sync                     # sync providers opted in via config
ai-config sync --provider cursor   # sync one provider (repeatable flag)
ai-config sync --all               # sync every known provider
ai-config sync --project           # project-level targets (must be in a repo)
ai-config sync --prune             # remove MCP servers no longer in scope

Sync is opt-in. Bare ai-config sync only writes to providers with "providers.<name>.sync": true in config.json. Detection alone never pushes config (or credentials in MCP env) into a provider file. Providers can instead read the unified config directly - see Provider Integration.

By default sync merges: existing keys in provider files are preserved, so servers added outside the unified config survive a sync. --prune makes the provider's MCP list an exact mirror of its scoped unified set, removing extras. Pruned files get a .backup copy first; combine with --dry-run to preview removals safely.

Per-provider MCP scoping lives in ~/.agents/config/config.json:

{
  "providers": {
    "cursor": { "mcp": { "include": ["github"] } },
    "claude": { "mcp": { "exclude": ["internal-tools"] } }
  }
}

include is an allowlist; exclude filters the full set. Use it to keep credential-bearing servers out of providers that don't need them. Servers flagged "disabled": true in mcp-config.json are never exported, even when named in include. See Configuration.

What gets written per provider:

• MCP servers: translated to each provider's shape - mcpServers (Cursor, Claude, Windsurf, Devin, Gemini), servers with type fields (VS Code), context_servers (Zed, stdio only), TOML [mcp_servers.*] (Codex), or a YAML list (Continue)
• Rules: unified AGENTS.md content written as a managed block (<!-- BEGIN ai-config managed --> markers) in file targets like CLAUDE.md, GEMINI.md, .rules, .github/copilot-instructions.md, or as dedicated files like .cursor/rules/ai-config.mdc
• Provider settings: providers.<name> settings merged into the provider's native config file
• Skills: ~/.agents/skills/* copied to provider skills directories

Existing native files are merged, not overwritten - other keys in a provider's config file are preserved, and managed-block rules can be re-synced safely.

ai-config set-config <provider> <key> <value>

Set a single configuration value for a provider.

ai-config set-config devin model your-model-name
ai-config set-config devin theme_mode dark
ai-config set-config devin verbose true

<value> is parsed as JSON first and falls back to a plain string, so true, 42, ["a"], and {"k":1} are stored as real JSON types.