CLI Reference

All commands are provided by the aiman binary.

Global flags

Flag	Description
--help	Show help for a command
--version	Print the binary version

aiman init

aiman init <repo-url> [--path <dir>]

Connects an inventory repository.

Arguments:

• <repo-url> — URL of the inventory Git repository.

Flags:

• --path <dir> — local path for cloning or registering the repository.

Behavior:

• clones or registers the inventory repository;
• creates the base structure for an empty repository;
• creates a local aim.local.yaml;
• writes the active repository to the global config;
• classifies existing files as adoptable, existing AIM, or conflicting.

aiman switch

aiman switch <path>

Switches the active inventory repository without cloning.

Use this if you have multiple local inventory repositories or need to run commands from a different directory.

aiman apply

aiman apply [--dry-run]

Applies the current local inventory to AI environments without any Git operations.

Flags:

• --dry-run — show what would be applied without writing files.

apply does not commit, does not push or fetch, and does not update published_hash or synced_hash.

aiman push

aiman push [--dry-run]

Validates the inventory, creates a commit, and pushes changes to the remote.

Flags:

• --dry-run — show the publish plan without committing or pushing.

push is blocked if the remote is ahead of the local state or if the Git state is unsafe.

aiman sync

aiman sync [--dry-run] [--force]

Fetches the published state from the remote and applies it to the local AI environments.

Flags:

• --dry-run — show the plan without writing to the repository or AI environments;
• --force — allow local changes to be overwritten when applying the published state.

sync does not perform merges. If the history has diverged, AIM stops and asks you to restore Git manually.

aiman status

aiman status

Shows the state of the active inventory repository:

• local unpublished changes;
• state of managed paths;
• published/synced hash information;
• remote state, if available.

Example output

Repository is in sync, inventory is applied:

Repository:
  repo:     git@github.com:you/aim-loadout.git
  status:   clean
  position: up-to-date
  HEAD:     a1b2c3d
  origin:   a1b2c3d

Environment:
  published: a1b2c3d
  applied:   a1b2c3d
  status:    applied

Local changes present with unpublished commits:

Repository:
  repo:     git@github.com:you/aim-loadout.git
  status:   dirty
  position: ahead 2 commit(s)
  HEAD:     e4f5g6h
  origin:   a1b2c3d
  action:   run aiman push

Environment:
  published: a1b2c3d
  applied:   not set
  status:    unknown

aiman doctor

aiman doctor

Diagnoses the local installation:

• active repository;
• detected AI environments;
• adapter paths;
• inventory item validity;
• required MCP env variables;
• remote availability and sync state.

Example output

Everything is healthy, all environments found:

Active Repo: /home/user/.aim/aim-loadout (from /home/user/.config/aim/config.yaml)

=== AI Environments ===
✓ claude-code   /home/user/.claude   found
✓ cursor        /home/user/.cursor   found
✗ codex         /home/user/.codex    not found

=== Skills ===
Found: 4 valid, 0 invalid

=== Sync State ===
synced_hash:    a1b2c3d
published_hash: a1b2c3d
remote HEAD:    a1b2c3d
status:         up-to-date

=== MCP Environment Variables ===
✓ context7 › UPSTASH_REDIS_REST_URL   — set

=== Issues ===
• codex: not installed or not found at /home/user/.codex

Issues present — AI environment not found, required variable not set:

Active Repo: /home/user/.aim/aim-loadout (from /home/user/.config/aim/config.yaml)

=== AI Environments ===
✓ claude-code   /home/user/.claude   found
✗ cursor        /home/user/.cursor   not found
✗ codex         /home/user/.codex    not found

=== Skills ===
Found: 2 valid, 1 invalid

=== Sync State ===
synced_hash:    not set
published_hash: not set
remote HEAD:    a1b2c3d
status:         not yet synced

=== MCP Environment Variables ===
✗ context7 › UPSTASH_REDIS_REST_URL   — missing (required)

=== Issues ===
• cursor: not installed or not found at /home/user/.cursor
• codex: not installed or not found at /home/user/.codex
• my-skill.md: invalid: name does not match filename
• context7 › UPSTASH_REDIS_REST_URL — missing (required)

aiman add

aiman add skill <file|-> [--name <string>] [--overwrite]
aiman add mcp <file|-> [--name <string>] [--overwrite]

Adds an inventory item (skill or MCP server) to the local repository from a file or stdin.

aiman add skill

aiman add skill <file|->
aiman add skill ~/Downloads/my-skill.md
aiman add skill -

Reads a skill from a file or stdin (-), validates the frontmatter, determines the name, and writes the file as skills/<name>.md in the active inventory repository.

Arguments:

• <file|-> — path to the skill file, or - to read from stdin.

Flags:

• --name <string> — override the skill name; if not set, the name is taken from the file's frontmatter.
• --overwrite — overwrite an existing skill on content conflict.

Behavior:

• if skills/<name>.md already exists with the same content — the command succeeds with no changes;
• if skills/<name>.md already exists with different content and --overwrite is not set — returns an error with a hint to use --overwrite.

Add from a file:

aiman add skill ~/Downloads/create-spec.md

Add from stdin:

cat ~/Downloads/create-spec.md | aiman add skill -

aiman add mcp

aiman add mcp <file|->
aiman add mcp jira.yaml
aiman add mcp -

Reads an MCP server description from a YAML file or stdin (-), applies env-strip, and writes the result to the active inventory repository.

Arguments:

• <file|-> — path to the MCP server YAML file, or - to read from stdin.

Flags:

• --name <string> — override the server name; if not set, the name is taken from the file's name field.
• --overwrite — overwrite an existing MCP server on content conflict.

Behavior:

• if mcp/<name>.yaml already exists with the same content — the command succeeds with no changes;
• if mcp/<name>.yaml already exists with different content and --overwrite is not set — returns an error with a hint to use --overwrite.

Env-strip: env fields with a populated value are not saved in mcp/<name>.yaml. Instead, the actual values are written to aim.local.yaml under the key mcp_env: {<name>.<VAR>: value}. The inventory stores only descriptors: name, description, required, example. Since aim.local.yaml is excluded from Git, secrets never enter the repository.

Example input file:

name: jira
description: Jira MCP server
command: npx
args: [-y, mcp-jira]
targets: [claude_code]
env:
  - name: JIRA_API_KEY
    description: Jira API key
    required: true
    value: "secret123"

After the command:

• mcp/jira.yaml contains the descriptor without the value field;
• aim.local.yaml contains mcp_env: {jira.JIRA_API_KEY: "secret123"}.

Add from a file:

aiman add mcp jira.yaml

Add from stdin:

cat jira.yaml | aiman add mcp -

Override the server name:

aiman add mcp jira.yaml --name jira-work

Overwrite on conflict:

aiman add mcp jira.yaml --overwrite

---

aiman import

aiman import skill <name> --from <env> [--dry-run] [--overwrite]
aiman import mcp <name> --from <env> [--dry-run] [--overwrite] [--targets all]

Imports an inventory item (skill or MCP server) from an installed AI environment into the local repository.

aiman import skill

aiman import skill <name> --from <env>
aiman import skill create-spec --from claude-code
aiman import skill create-spec --from claude-code --dry-run

Reads a skill by name from the specified AI environment, normalizes it, and writes it as skills/<name>.md in the active inventory repository.

Arguments:

• <name> — name of the skill to import.

Flags:

• --from <env> — import source (required). Accepted values: claude-code, cursor, codex.
• --dry-run — print the skill content without writing to disk.
• --overwrite — overwrite an existing skill on content conflict.

Skill sources by AI environment:

AI environment	Identifier	Skills path
Claude Code	claude-code	~/.claude/skills/*.md and ~/.claude/skills/<name>/SKILL.md
Codex CLI	codex	~/.codex/skills/<name>/SKILL.md
Cursor	cursor	No native skill concept — always returns an empty list

Behavior:

• if the skill is not found in the specified environment — returns an error;
• if skills/<name>.md already exists with the same content — succeeds with no changes;
• if skills/<name>.md already exists with different content and --overwrite is not set — returns an error with a hint to use --overwrite.

Import from Claude Code:

aiman import skill create-spec --from claude-code

Preview without writing:

aiman import skill create-spec --from claude-code --dry-run

aiman import mcp

aiman import mcp <name> --from <env> [--dry-run] [--overwrite] [--targets all]
aiman import mcp context7 --from claude-code
aiman import mcp jira --from cursor --dry-run
aiman import mcp context7 --from claude-code --targets all

Scans the live configuration of the specified AI environment, locates MCP servers, applies env-strip, and writes the descriptor to the active inventory repository.

Arguments:

• <name> — name of the MCP server to import.

Flags:

• --from <env> — import source (required). Accepted values: claude-code, cursor, codex.
• --dry-run — print the YAML descriptor without writing files.
• --overwrite — overwrite the existing file if content differs.
• --targets all — set all three adapters (claude-code, cursor, codex) as target environments in the descriptor. By default, only the source environment is used.

Behavior:

• Env-strip: real env variable values are not saved in mcp/<name>.yaml. Instead, they are written to aim.local.yaml under the key mcp_env: {<name>.<VAR>: value}. Only descriptors — name, required — go into the inventory. Since aim.local.yaml is excluded from Git, secrets never enter the repository.
• Deduplication: if the same server name appears multiple times with the same command and arguments, the first entry is used.
• Ambiguity (AmbiguousError): if the same server name appears with different commands or arguments, the command fails — you must explicitly specify the source via --from.
• Server not found: if no server with the given name exists in the environment config, the command fails with MCP server "<name>" not found in <env>.
• Unknown environment: if the --from value is not recognized, the command fails with unknown environment: X; available: claude-code, cursor, codex.
• if mcp/<name>.yaml already exists with the same content — succeeds with no changes;
• if mcp/<name>.yaml already exists with different content and --overwrite is not set — returns an error with a hint to use --overwrite.

MCP configuration sources by AI environment:

AI environment	Identifier	Configuration file
Claude Code	claude-code	~/.claude/settings.json (key mcpServers)
Cursor	cursor	~/.cursor/mcp.json (key mcpServers)
Codex CLI	codex	~/.codex/config.toml (section mcp_servers)

Import from Claude Code:

aiman import mcp context7 --from claude-code

Preview without writing:

aiman import mcp context7 --from claude-code --dry-run

Import with all adapters set as targets:

aiman import mcp context7 --from claude-code --targets all

Overwrite if the file already exists:

aiman import mcp context7 --from claude-code --overwrite

---

Commands outside the current public scope

aiman list may be present in the codebase as a historical command, but its full public contract is deferred until loadouts and a complete inventory view are implemented.