CLI анықтамалығы

Барлық командаларды aiman бинарлық файлы ұсынады.

Жаһандық флагтар

Флаг	Сипаттама
--help	Команда үшін анықтаманы көрсету
--version	Бинарлық файл нұсқасын көрсету

aiman init

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

Инвентарь репозиторийін жалғайды.

Аргументтер:

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

Флагтар:

• --path <dir> — clone немесе репозиторийді тіркеу үшін жергілікті жол.

Мінез-құлық:

• инвентарь репозиторийін клондайды немесе тіркейді;
• бос репозиторий үшін құрылым жасайды;
• жергілікті aim.local.yaml жасайды;
• жаһандық конфигіге белсенді репозиторийді жазады;
• бар файлдарды adoptable, existing AIM немесе conflicting ретінде классификациялайды.

aiman switch

aiman switch <path>

Clone-сіз белсенді инвентарь репозиторийін ауыстырады.

Бірнеше жергілікті инвентарь репозиторийіңіз болса немесе басқа каталогтан командалар іске қосу қажет болса пайдаланыңыз.

aiman apply

aiman apply [--dry-run]

Ағымдағы жергілікті инвентарьды Git операцияларынсыз AI орталарына қолданады.

Флагтар:

• --dry-run — файлдарды жазбастан жергілікті инвентарь мен орнатылған AI орталары арасындағы sha256-дельтаны көрсету.

apply commit жасамайды, push/fetch орындамайды және published_hash немесе synced_hash-ті жаңартпайды.

apply шығару мысалы

Сәтті орындалған кезде apply нәтиже жолын шығарады. Кез келген AI ортасында өзгерістер болса, нәтиже жолынан кейін екі бос орын шегіністе және A (жаңа артефакт) мен M (өзгертілген) маркерлерімен өзгерістер блогы басылады:

applied: 21 skills, 1 MCP server → 3 environments
  A skills/refactor-helper.md   (new in all environments)
  M skills/commit-message.md    (updated in claude-code, cursor)

Нәтиже жолындағы санауыштар (21 skills, 1 MCP server) — операция көлемі: барлығы қанша қолданылды. Төмендегі блок — өзгерістер құрамы: не дәл қосылды немесе жаңартылды. Бұл бөлек сандар: 21 skills — 21 өзгеріс емес, жалпы 21 дағды.

Ортасы ешқандай өзгеріссіз сәйкес болса, блоксыз тек нәтиже жолы басылады:

applied: 21 skills, 1 MCP server → 3 environments

apply --dry-run шығару мысалы

Инвентарь орнатылған AI орталарымен сәйкес:

[dry-run] nothing to apply — environments match local inventory

Өзгерістер бар:

[dry-run] would apply 2 changes to 2 environments (claude-code, cursor):
  A skills/new-skill.md   (new in all environments)
  M skills/existing.md   (differs in cursor)
[dry-run] MCP context7 → claude-code, cursor

MCP серверлері үшін apply --dry-run тек нысана AI орталарын көрсетеді және дельтаны есептемейді: AIM ортада орнатылған MCP конфигурациясын инвентарь дескрипторымен салыстырмайды. Толығырақ — Белгілі шектеу: MCP конфигтерінің дельтасы.

Өзгерістер тізімі 20 жолдан асса, ол қысқартылады:

  A skills/skill-1.md
  A skills/skill-2.md
  … and 15 more

Белгілі шектеу: MCP конфигтерінің дельтасы

Дағдылар үшін AIM дельтаны есептейді: инвентарь мазмұнын әр AI ортасында орнатылған файлмен салыстырады және өзгерістерді A/M маркерлерімен белгілейді.

MCP серверлері үшін дельта әзірге есептелмейді. AI орталары MCP-ны ортақ конфигтерге (~/.claude.json, mcp.json, config.toml) жазады, ал орнатылған фрагментті дескриптормен салыстыру осы конфигтерді талдап нормалайтынды талап етеді — бұл кейінге қалдырылды. Сондықтан шығарылымда MCP жолдары тек нысана орталарды көрсетеді, A/M маркерлерінсіз.

MCP сервері жанындағы маркердің болмауы оның өзгермейтінін білдірмейді. Бұл AIM оның ортадағы күйін тексермейтінін білдіреді. Дағдылар үшін бұл дельтамен тексерілген, MCP үшін — тексерілмеген.

aiman push

aiman push [--dry-run]

Инвентарьды валидациялайды, commit жасайды және өзгерістерді remote-қа жібереді.

Флагтар:

• --dry-run — commit/push-сіз жариялау жоспарын көрсету.

push remote жергілікті күйден жаңа болса немесе Git қауіпсіз емес күйде болса бұғатталады.

Frontmatter валидациясы: frontmatter өрісі (файл денесінен басқа) қате болса, push stderr-ге warning: шығарып жұмысты жалғастырады. Файл денесіндегі (body) қателер блоктаушы болып қалады: push error: шығарып жариялауды тоқтатады.

push шығару мысалы

Сәтті орындалған кезде push жарияланған commit-тің хешімен нәтиже жолын шығарады. Инвентарьда өзгерістер болса, нәтиже жолынан кейін өзгерістер блогы басылады: қандай файлдар жарияланды (A — жаңа, M — өзгерілген):

published: 96e091b · 19 skills, 1 MCP server
  M skills/commit-message.md
  A mcp/jira.yaml

Өзгеріс жоқ болса, блоксыз тек нәтиже жолы басылады.

push --dry-run шығару мысалы

Жұмыс ағашы таза:

[dry-run] nothing to publish — working tree is clean

Жариялауға өзгерістер бар:

[dry-run] would publish managed changes:
  M skills/review-code.md
  A mcp/jira.yaml
  validated inventory: 5 skills, 1 MCP server

aiman sync

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

Remote-тан жарияланған күйді алады және оны жергілікті AI орталарына қолданады.

Флагтар:

• --dry-run — репозиторий мен AI орталарына жазбастан жоспарды көрсету;
• --force — remote-пен атауы сәйкес келетін бақылаусыз файлдарды жойып, жарияланған күйді қолдану. Атауы сәйкес келмейтін файлдар сақталады.

sync merge орындамайды. Тарих айырылып кетсе, AIM тоқтап, Git-ті қолмен қалпына келтіруді сұрайды.

skills/ және mcp/ папкасындағы бақылаусыз файлдар sync-ті блоктамайды — тек remote-тан келетін файлмен атауы сәйкес келгенде ғана бұғат жасалады. Қақтығыс болса, sync тоқтайды және проблемалық файлдар тізімін шығарады.

sync шығару мысалы

Сәтті орындалған кезде sync қолданылған күйдің хешімен нәтиже жолын шығарады. Remote-тан өзгерістер келсе, нәтиже жолынан кейін инвентарьда не жаңарды (A — жаңа, M — өзгерілген, D — жойылды) — өзгерістер блогы басылады:

synced: 67451fc · 21 skills, 1 MCP server → 3 environments
  M skills/commit-message.md
  A skills/refactor-helper.md

apply-дегі сияқты нәтиже жолындағы санауыштар — операция көлемі (барлығы қолданылды), ал блок — келіп түскен өзгерістер құрамы. 21 skills — 21 өзгеріс емес, жалпы 21 дағды.

Remote-тан ештеңе келмесе (жергілікті күй origin/main-мен сәйкес болса), блоксыз тек нәтиже жолы басылады:

synced: 67451fc · 21 skills, 1 MCP server → 3 environments

--force флагымен AIM қолдануға дейін қақтығысатын бақылаусыз файлдарды жойып, не жойғанын хабарлайды. Бұл есеп нәтиже жолынан бұрын басылады:

discarded untracked files (--force):
  skills/draft.md
  mcp/local-only.yaml
synced: 67451fc · 21 skills, 1 MCP server → 3 environments

Жою туралы есеп өшіру мүмкіндігінсіз әрқашан шығарылады: --force файлдарды біржола жояды және AIM мұны үнсіз жасамайды.

sync --dry-run шығару мысалы

Remote-тан қолдануға ештеңе жоқ (жергілікті күй origin/main-мен сәйкес):

[dry-run] nothing to sync — environments up to date with origin/main

Қолдануға өзгерістер бар:

[dry-run] would sync 2 changes from origin/main → 3 environments:
  M skills/commit-message.md
  A skills/refactor-helper.md

aiman status

aiman status

Белсенді инвентарь репозиторийінің күйін көрсетеді: origin/main-ге қатысты позицияны, AI орталарының күйін және skills/ мен mcp/-дегі әлі жарияланбаған өзгерістер тізімін.

aiman status remote-қа жүгінеді. Позицияны есептеу алдында команда Git fetch орындайды — «инвентарымда жарияланған күйге қатысты не өзгерді» деген сұраққа жауап береді, ал бұл сұрақ remote күйін қамтиды. Fetch-сіз жауап ескірген жергілікті ref бойынша есептелер еді және дұрыс болмауы мүмкін (remote алға кеткен кезде up-to-date көрсетуі мүмкін).

Бұл — жергілікті git status-тан саналы айырмашылық. git status-тың желілік жүгінісі жоқ, себебі оның сұрағы жергілікті жұмыс ағашы туралы. aiman status-тың сұрағы басқа және remote-ты қамтиды, сондықтан fetch-ке кеткен қысқа кідіріс — күтілетін мінез-құлық, ақаулық емес.

TODO: fetch кезінде спиннер қосу

Fetch қатаң таймаутпен орындалады. Remote қолжетімсіз болса, команда қатып қалмайды: Position: өрісі unknown (remote unreachable) мәнін алады, stderr-ге warning: cannot reach remote repository басылады, қайтару коды 0 болып қалады.

Position: өрісінің мүмкін мәндері: up-to-date with origin/main | N commits ahead of origin/main | N commits behind of origin/main | diverged from origin/main (N ahead, M behind) | unknown (remote unreachable).

Environments: өрісінің мүмкін мәндері: applied (synced <hash>) | unknown | needs sync (N commits not applied).

Өзгерістер тізімі 20 жолдан асса, ол … and N more жазуымен қысқартылады.

Шығару мысалы

Репозиторий синхрондалған, инвентарь қолданылған:

Repository:   git@github.com:you/aim-loadout.git
Position:     up-to-date with origin/main
Environments: applied (synced a1b2c3d)

Working tree matches origin/main · nothing to publish

Жарияланбаған өзгерістер бар:

Repository:   git@github.com:you/aim-loadout.git
Position:     2 commits ahead of origin/main
Environments: needs sync (2 commits not applied)

Changes not yet published (origin/main → working tree):
  A skills/new-skill.md
  M skills/existing.md

  run aiman push to publish
  run aiman sync to apply

Remote қолжетімсіз (желі жоқ немесе репозиторийге қол жеткізілмейді):

Repository:   git@github.com:you/aim-loadout.git
Position:     unknown (remote unreachable)
Environments: applied (synced a1b2c3d)

Working tree matches origin/main · nothing to publish

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|dir|-> [--name <string>] [--overwrite]
aiman add mcp <file|-> [--name <string>] [--overwrite]

Файлдан, директориядан немесе stdin-нен жергілікті репозиторийге инвентарь элементін (дағды немесе MCP сервері) қосады.

aiman add skill

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

Файлдан, директориядан немесе stdin-нен (-) skill оқиды, frontmatter-ді валидациялайды, атауды анықтайды және белсенді инвентарь репозиторийіне жазады.

Аргументтер:

• <file|dir|-> — skill файлының жолы, қалталық дағдыға жол (немесе оның SKILL.md-іне), не stdin-нен оқу үшін -.

Флагтар:

• --name <string> — skill атауын қайта анықтау; белгіленбесе, атау жалпақ skill үшін файлдың frontmatter-інен, қалталық дағды үшін директория атынан алынады.
• --overwrite — мазмұн конфликті кезінде бар skill-ді қайта жазу.

Мінез-құлық:

• SKILL.md аталмаған жалпақ файл немесе stdin — skills/<name>.md ретінде жазылады;
• директорияға немесе оның ішіндегі SKILL.md файлына жол — қалталық дағды ретінде танылады және skills/<name>/ ішіне тұтасымен көшіріледі (SKILL.md + қасындағы барлық анықтамалық файлдар). Екі жол нұсқасы да бірдей нәтиже береді;
• директорияда SKILL.md болмаса — жүйелік "is a directory" емес, нақты қате қайтарылады;
• skills/<name>.md (жалпақ) немесе skills/<name>/SKILL.md (қалталық дағды) бірдей мазмұнмен бұрыннан болса — өзгеріссіз сәтті аяқталады; қалталық дағды үшін тек SKILL.md мазмұны салыстырылады, анықтамалық файлдар салыстыруға кірмейді;
• мақсат орны басқа мазмұнмен болса және --overwrite белгіленбесе — --overwrite пайдалануды ұсынатын қате қайтарады.

Файлдан қосу мысалы:

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

Stdin-нен қосу мысалы:

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

Қалталық дағдыны қосу мысалы (екі нұсқа тең):

aiman add skill ~/Downloads/get-team-tasks
aiman add skill ~/Downloads/get-team-tasks/SKILL.md

Сәтті қосу кезіндегі шығару:

added: skill create-spec

Skill инвентарьда бірдей мазмұнмен бұрыннан болса (операция талап етілмейді):

up to date: skill create-spec · already identical

aiman add mcp

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

YAML файлынан немесе stdin-нен (-) MCP сервері сипаттамасын оқиды, env-strip қолданады және нәтижені белсенді инвентарь репозиторийіне жазады.

Аргументтер:

• <file|-> — MCP сервері YAML файлының жолы немесе stdin-нен оқу үшін -.

Флагтар:

• --name <string> — сервер атауын қайта анықтау; белгіленбесе, атау файлдың name өрісінен алынады.
• --overwrite — мазмұн конфликті кезінде бар MCP серверін қайта жазу.

Мінез-құлық:

• mcp/<name>.yaml бірдей мазмұнмен бұрыннан болса — команда өзгеріссіз сәтті аяқталады;
• mcp/<name>.yaml басқа мазмұнмен болса және --overwrite белгіленбесе — --overwrite пайдалануды ұсынатын қате қайтарады.

Env-strip: value толтырылған env өрістері 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

Сәтті қосу кезіндегі шығару:

added: mcp jira

MCP сервері инвентарьда бірдей мазмұнмен бұрыннан болса (операция талап етілмейді):

up to date: mcp jira · already identical

---

aiman import

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

Орнатылған AI ортасынан жергілікті репозиторийге инвентарь элементін (дағды немесе MCP сервері) импорттайды.

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 --print

Көрсетілген AI ортасынан атауы бойынша skill оқиды, нормалайды және белсенді инвентарь репозиторийінде skills/<name>.md ретінде жазады.

Аргументтер:

• <name> — импорттайтын skill атауы.

Флагтар:

• --from <env> — импорт көзі (міндетті). Қолжетімді мәндер: claude-code, cursor, codex.
• --print — дискіге жазбастан skill мазмұнын stdout-қа шығару.
• --overwrite — мазмұн конфликті кезінде бар skill-ді қайта жазу.

AI ортасы бойынша skill көздері:

AI ортасы	Идентификатор	Skill жолдары
Claude Code	claude-code	~/.claude/skills/*.md және ~/.claude/skills/<name>/SKILL.md
Codex CLI	codex	~/.codex/skills/<name>/SKILL.md
Cursor	cursor	Skill-дің нативті тұжырымдамасы жоқ — әрдайым бос тізім қайтарады

Мінез-құлық:

• skill көрсетілген ортада табылмаса — қате қайтарады;
• skills/<name>.md бірдей мазмұнмен бұрыннан болса — өзгеріссіз сәтті аяқталады;
• skills/<name>.md басқа мазмұнмен болса және --overwrite белгіленбесе — --overwrite пайдалануды ұсынатын қате қайтарады.

Claude Code-тан импорттау мысалы:

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

Сәтті импорттау кезіндегі шығару:

imported: skill create-spec · from claude-code

Skill инвентарьда бірдей мазмұнмен бұрыннан болса (операция талап етілмейді):

up to date: skill create-spec · already identical

Жазбасыз тексеру:

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

aiman import mcp

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

Көрсетілген AI ортасының тірі конфигурациясын сканерлейді, MCP серверлерін табады, env-strip қолданады және дескрипторды белсенді инвентарь репозиторийіне жазады.

Аргументтер:

• <name> — импорттайтын MCP сервері атауы.

Флагтар:

• --from <env> — импорт көзі (міндетті). Қолжетімді мәндер: claude-code, cursor, codex.
• --print — файлдарды жазбастан YAML дескрипторын stdout-қа шығару.
• --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 пайдалануды ұсынатын қате қайтарады.

AI ортасы бойынша MCP конфигурация көздері:

AI ортасы	Идентификатор	Конфигурация файлы
Claude Code	claude-code	~/.claude.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

Сәтті импорттау кезіндегі шығару:

imported: mcp context7 · from claude-code

MCP серверінде толтырылған env айнымалылары болса, олар aim.local.yaml-ға жазылады:

imported: mcp context7 · from claude-code · secrets stored in aim.local.yaml

MCP сервері инвентарьда бірдей мазмұнмен бұрыннан болса (операция талап етілмейді):

up to date: mcp context7 · already identical

Жазбасыз тексеру:

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

Барлық адаптерлерді нысана ретінде белгілеп импорттау:

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

Файл бұрыннан болса қайта жазу:

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

---

Ағымдағы жалпыға ашық scope-тан тыс командалар

aiman list кодтық базада тарихи команда ретінде болуы мүмкін, бірақ толыққанды жалпыға ашық контракт loadouts пен толық inventory view жүзеге асырылғанға дейін қалдырылды.