Справочник CLI

Все команды предоставляет бинарник aiman.

Глобальные флаги

Флаг	Описание
--help	Показать help для команды
--version	Показать версию бинарника

aiman init

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

Подключает репозиторий инвентаря.

Аргументы:

• <repo-url> — URL Git-репозитория инвентаря.

Флаги:

• --path <dir> — локальный путь для clone или регистрации репозитория.

Поведение:

• клонирует или регистрирует репозиторий инвентаря;
• создаёт структуру для пустого репозитория;
• создаёт локальный aim.local.yaml;
• записывает активный репозиторий в глобальный конфиг;
• классифицирует существующие файлы как adoptable, existing AIM или conflicting.

aiman switch

aiman switch <path>

Переключает активный репозиторий инвентаря без clone.

Используйте, если у вас несколько локальных репозиториев инвентаря или нужно запустить команды из другой директории.

aiman apply

aiman apply [--dry-run]

Применяет текущий локальный инвентарь в AI-среды без Git-операций.

Флаги:

• --dry-run — показать, что будет применено, без записи файлов.

apply не делает commit, не выполняет push/fetch и не обновляет published_hash или synced_hash.

aiman push

aiman push [--dry-run]

Валидирует инвентарь, создаёт commit и отправляет изменения в remote.

Флаги:

• --dry-run — показать план публикации без commit/push.

push блокируется, если remote новее локального состояния или есть небезопасное состояние Git.

aiman sync

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

Получает опубликованное состояние из remote и применяет его в локальные AI-среды.

Флаги:

• --dry-run — показать план без записи в репозиторий и AI-среды;
• --force — разрешить потерю локальных изменений при применении опубликованного состояния.

sync не выполняет merge. Если история разошлась, AIM останавливается и просит восстановить Git вручную.

aiman status

aiman status

Показывает состояние активного репозитория инвентаря:

• локальные неопубликованные изменения;
• состояние managed paths;
• сведения о published/synced hash;
• состояние remote, если его можно получить.

Пример вывода

Репозиторий синхронизирован, инвентарь применён:

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

Есть локальные изменения и неопубликованные коммиты:

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

Диагностирует локальную установку:

• активный репозиторий;
• найденные AI-среды;
• пути адаптеров;
• валидность элементов инвентаря;
• обязательные MCP env-переменные;
• доступность remote и состояние синхронизации.

Пример вывода

Всё в порядке, все среды найдены:

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

Есть проблемы — AI-среда не найдена, обязательная переменная не задана:

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]

Добавляет элемент инвентаря (навык или MCP-сервер) в локальный репозиторий из файла или stdin.

aiman add skill

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

Читает скилл из файла или из stdin (-), валидирует frontmatter, определяет имя и записывает файл как skills/<name>.md в активном репозитории инвентаря.

Аргументы:

• <file|-> — путь к файлу скилла или - для чтения из stdin.

Флаги:

• --name <string> — переопределить имя скилла; если не указан, имя берётся из frontmatter файла.
• --overwrite — перезаписать существующий скилл при конфликте содержимого.

Поведение:

• если skills/<name>.md уже существует с тем же содержимым — команда завершается успешно без изменений;
• если skills/<name>.md уже существует с другим содержимым и --overwrite не указан — возвращает ошибку с подсказкой использовать --overwrite.

Пример добавления из файла:

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

Пример добавления из stdin:

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

aiman add mcp

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

Читает описание MCP-сервера из YAML-файла или из stdin (-), применяет env-strip и записывает результат в активный репозиторий инвентаря.

Аргументы:

• <file|-> — путь к YAML-файлу MCP-сервера или - для чтения из stdin.

Флаги:

• --name <string> — переопределить имя сервера; если не указан, имя берётся из поля name файла.
• --overwrite — перезаписать существующий MCP-сервер при конфликте содержимого.

Поведение:

• если mcp/<name>.yaml уже существует с тем же содержимым — команда завершается успешно без изменений;
• если mcp/<name>.yaml уже существует с другим содержимым и --overwrite не указан — возвращает ошибку с подсказкой использовать --overwrite.

Env-strip: поля env с заполненным value не сохраняются в mcp/<name>.yaml. Вместо этого реальные значения записываются в aim.local.yaml под ключом mcp_env: {<name>.<VAR>: value}. В инвентаре хранятся только дескрипторы: name, description, required, example. Файл aim.local.yaml исключён из Git, поэтому секреты не попадают в репозиторий.

Пример входного файла:

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"

После выполнения команды:

• mcp/jira.yaml содержит дескриптор без поля value;
• aim.local.yaml содержит mcp_env: {jira.JIRA_API_KEY: "secret123"}.

Пример добавления из файла:

aiman add mcp jira.yaml

Пример добавления из stdin:

cat jira.yaml | aiman add mcp -

Переопределить имя сервера:

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

Перезаписать при конфликте:

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]

Импортирует элемент инвентаря (навык или MCP-сервер) из установленной AI-среды в локальный репозиторий.

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

Читает скилл по имени из указанной AI-среды, нормализует его и записывает как skills/<name>.md в активном репозитории инвентаря.

Аргументы:

• <name> — имя скилла, который нужно импортировать.

Флаги:

• --from <env> — источник импорта (обязательный). Доступные значения: claude-code, cursor, codex.
• --dry-run — вывести содержимое скилла без записи на диск.
• --overwrite — перезаписать существующий скилл при конфликте содержимого.

Источники скиллов по AI-средам:

AI-среда	Идентификатор	Путь к скиллам
Claude Code	claude-code	~/.claude/skills/*.md и ~/.claude/skills/<name>/SKILL.md
Codex CLI	codex	~/.codex/skills/<name>/SKILL.md
Cursor	cursor	Нет нативного понятия скиллов — всегда возвращает пустой список

Поведение:

• если скилл не найден в указанной среде — возвращает ошибку;
• если skills/<name>.md уже существует с тем же содержимым — завершается успешно без изменений;
• если skills/<name>.md уже существует с другим содержимым и --overwrite не указан — возвращает ошибку с подсказкой использовать --overwrite.

Пример импорта из Claude Code:

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

Проверка без записи:

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

Сканирует живую конфигурацию указанной AI-среды, находит MCP-серверы, применяет env-strip и записывает дескриптор в активный репозиторий инвентаря.

Аргументы:

• <name> — имя MCP-сервера для импорта.

Флаги:

• --from <env> — источник импорта (обязательный). Доступные значения: claude-code, cursor, codex.
• --dry-run — вывести YAML-дескриптор без записи файлов.
• --overwrite — перезаписать существующий файл, если содержимое отличается.
• --targets all — задать все три адаптера (claude-code, cursor, codex) как целевые среды в дескрипторе. По умолчанию используется только среда-источник.

Поведение:

• Env-strip: реальные значения env-переменных не сохраняются в mcp/<name>.yaml. Вместо этого они записываются в aim.local.yaml под ключом mcp_env: {<name>.<VAR>: value}. В инвентарь попадают только дескрипторы: name, required. Файл aim.local.yaml исключён из Git, поэтому секреты не попадают в репозиторий.
• Дедупликация: если одно имя сервера встречается несколько раз с одинаковой командой и аргументами, берётся первая запись.
• Неоднозначность (AmbiguousError): если одно имя сервера встречается с разными командами или аргументами, команда завершается с ошибкой — нужно явно указать источник через --from.
• Сервер не найден: если сервер с указанным именем отсутствует в конфигурации среды, команда завершается с ошибкой MCP server "<name>" not found in <env>.
• Неизвестная среда: если значение --from не распознано, команда завершается с ошибкой unknown environment: X; available: claude-code, cursor, codex.
• если mcp/<name>.yaml уже существует с тем же содержимым — команда завершается успешно без изменений;
• если mcp/<name>.yaml уже существует с другим содержимым и --overwrite не указан — возвращает ошибку с подсказкой использовать --overwrite.

Источники MCP-конфигурации по AI-средам:

AI-среда	Идентификатор	Файл конфигурации
Claude Code	claude-code	~/.claude/settings.json (ключ mcpServers)
Cursor	cursor	~/.cursor/mcp.json (ключ mcpServers)
Codex CLI	codex	~/.codex/config.toml (секция mcp_servers)

Пример импорта из Claude Code:

aiman import mcp context7 --from claude-code

Проверка без записи:

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

Импорт с установкой всех адаптеров как целевых сред:

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

Перезаписать, если файл уже существует:

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

---

Команды вне текущего публичного scope

aiman list может присутствовать в кодовой базе как историческая команда, но полноценный публичный контракт отложен до реализации loadouts и полного inventory view.