install

Устанавливает конфигурацию адаптера окружения из общего профиля.

СинтаксисCopy Anchor Link

apothem install --harness NAME|all [--profile PATH] [--dry-run]
                 [--clean|--fresh] [--yes] [--project PATH]
                 [--quiet|-q] [--verbose|-v]
                 [--format plain|json] [--json] [--no-color]

Загружает и проверяет общий профиль, выбирает именованный адаптер или набор all уровня всего реестра, проверяет план материализации и записывает нативную конфигурацию окружения вместе со вспомогательными группами. Адаптеры с областью проекта требуют --project PATH.

Псевдоним в продолженной форме apothem installing (принимается также как apothem Installing) разрешается в тот же обработчик.

Первый запуск без профиляCopy Anchor Link

Когда --profile не указан и по пути по умолчанию (~/.config/apothem/profile.yaml) профиля нет, install сначала записывает туда стартовый профиль, печатает Created a starter profile at <path> и продолжает работу. Стартовый профиль содержит поля идентичности-заполнители, поэтому установка также печатает примечание об идентичности-заполнителе; настройте профиль под себя, затем выполните update, чтобы применить его. При --json создание профиля сообщается как запись warnings с "operation": "profile_created".

• --dry-run никогда не записывает профиль: предпросмотр использует стартовый профиль в памяти и сообщает "operation": "profile_scaffold_preview".
• Явно указанный --profile PATH, который не существует, никогда не создаётся; команда завершается с кодом 1 и profile.not_found.

Предпросмотр радиуса пораженияCopy Anchor Link

install --harness all разветвляется на смешанные области: адаптеры с областью проекта записывают в корень, переданный через --project, а адаптеры с областью пользователя записывают в ваш домашний каталог, то есть за пределами этого корня. Прежде чем установка запишет какой-либо файл, команда выводит конкретные цели, сгруппированные под двумя заголовками: цели внутри корня проекта и цели в вашем домашнем каталоге. Третий заголовок перечисляет общие папки в вашем домашнем каталоге, в которые записывают адаптеры с областью проекта за пределами --project: папку навыков и ~/.config/apothem/ (см. Папки в вашем домашнем каталоге). Единственное исключение — --clean: его шаг очистки выполняется до этого предварительного просмотра, записывает резервную копию и удаляет прежние цели, как описано ниже.

Когда выбор записывает за пределы корня проекта, будь то в папку адаптера с корнем в домашнем каталоге или в общую папку, интерактивное подтверждение защищает записи, корнем которых служит домашний каталог. --yes, неинтерактивная оболочка (без TTY), --dry-run и --format json — каждый из этих вариантов продолжает работу без запроса. Только --dry-run ничего не записывает; --format json пропускает предпросмотр и запрос подтверждения, но всё равно выполняет записи. Отказ в запросе по домашнему каталогу прерывает установку до записи. С --clean сначала выполняется шаг очистки с нуля под собственным подтверждением для каждой цели: он записывает резервную копию в ~/.apothem/backups и удаляет подтверждённые цели. Эти удаления и резервная копия сохраняются, если запрос на установку отклонён.

Папки в вашем домашнем каталогеCopy Anchor Link

Семь адаптеров с областью проекта записывают навыки Apothem, а также правила и шаблоны, на которые ссылаются навыки, в папки в домашнем каталоге пользователя:

cursor, github-copilot, windsurf, zed  ->  ~/.agents/skills/ (codex writes it too)
codebuddy                               ->  ~/.codebuddy/skills/
kiro                                    ->  ~/.kiro/skills/
trae                                    ->  ~/.trae/skills/
all seven                               ->  ~/.config/apothem/rules/ and templates/ (codex uses them too)

• --project выбирает файл правил и проект, к которому относится установка. Он не меняет того, куда попадают навыки: установка с --project A и установка с --project B записывают одни и те же папки.
• Каждая установка, которая называет папку, записывает одни и те же файлы. Вторая установка находит их и сообщает unchanged, а порядок, в котором вы выполняете установки, не имеет значения.
• Папки в домашнем каталоге записываются раньше всего, что находится в проекте. Если запись туда завершается сбоем, установка адаптера останавливается с ошибкой, а проект остаётся неизменным. Ошибка называет мешающий путь, например файл с именем ~/.agents там, где должна быть папка.
• Каждая папка навыка записывается в скрытую папку .<name>.apothem-staging рядом с ней и переименовывается на место по завершении, поэтому неудачная или прерванная запись никогда не оставляет наполовину записанную папку навыка под её окончательным именем. Запустите установку снова, чтобы завершить её; она заменяет оставшуюся промежуточную папку.
• Символическая ссылка на месте одной из этих папок или выше неё, какие создают менеджеры dotfile-файлов для ~/.config или ~/.agents, используется, когда она ведёт куда-либо внутри вашего домашнего каталога. Ссылка, которая выходит за пределы вашего домашнего каталога, останавливает установку с target escapes the allowed materialization root, как и ссылка внутри папки навыка.
• Установка не добавляет в ваш репозиторий ни одного файла навыка или правил. Проект получает файл правил адаптера, а также папку данных .apothem/, которую создаёт каждая установка в проект.
• Папка навыка, которая носит имя навыка Apothem и которую Apothem не записывал, пропускается. Установка печатает строку Warning:, а конверт --format json содержит запись warnings с "outcome": "warning" и "operation": "skill_conflict", которая называет эту папку. Переименуйте или переместите папку, затем выполните update.
• Каждая такая установка, обновление и пробный запуск печатают Note:, которое называет папки, записываемые за пределами --project. В конверте JSON это запись warnings с "operation": "user_level_write" и списком paths.

Примечания о возможностяхCopy Anchor Link

Каждый адаптер проецирует только те возможности, которые его окружение поддерживает нативно; о возможностях без нативной поверхности сообщается, они не отбрасываются молча. В режиме plain это одно сгруппированное примечание на окружение (например, Note: <harness> - 9 capabilities not projected; pass --verbose for detail); при --verbose каждая возможность печатает собственную строку с обоснованием. Любое другое предупреждение адаптера в режиме plain тоже печатается отдельной строкой Warning:, например предупреждение Zed, называющее файл инструкций, который оказывается скрыт новым .rules. Конверт --format json всегда содержит полный массив warnings независимо от уровня детализации.

Установка и обновление также печатают рекомендации в виде строк Note:. Рекомендация никогда не меняет того, что записывает установка. Когда установка записывает общий корень — путь, который загружают и другие инструменты (например, папка навыков ~/.agents/skills/), — примечание называет эти инструменты и заключает в скобки инструмент, который загружает путь только при некотором условии, например Open-Claw (only under its default state directory). Установка, которая записывает папку, в которую записывают и другие установки (роль holder), сообщает, что папка остаётся, пока не будет удалена последняя установка Apothem, которая её использует, и называет установки, которые используют её сейчас. Когда установка нацелена на инструмент, который уже загружает содержимое Apothem из общего корня другой установки, примечание называет установку, которая его поместила: зарегистрированного владельца, пока он ещё использует папку, иначе самую старую установку, которая её использует. В конверте --format json каждая рекомендация — это запись warnings с "outcome": "advisory" и "operation": "shared_root"; её role — это owner, holder или reader, holders перечисляет установки, использующие папку, а owner_of_record называет зарегистрированного владельца.

Установка, которая регистрирует хуки, также печатает примечания о файле хуков. Рекомендация hook_review называет шаг, который нужен инструменту, прежде чем он запустит хуки (перезапуск и проверка либо доверие к рабочей области), или опасность файла хуков, который фиксируется в репозитории и называет интерпретатор этой машины. Рекомендация hook_import появляется для инструмента, который также запускает хуки из файлов настроек Claude Code, например тех, что записывает установка Apothem для Claude Code, и называет собственный переключатель инструмента для отключения этого импорта и то, что этот переключатель также останавливает. Каждая из них — это запись warnings с "outcome": "advisory", harness, path файла хуков и message.

Команда хука держит путь к проекту и путь к интерпретатору внутри двойных кавычек, которые читают и sh, и Git Bash, и PowerShell. Путь, содержащий $, обратную кавычку, двойную кавычку или обратную косую черту, заставил бы команду запустить другой файл, поэтому установка (и --dry-run) останавливается с ошибкой, которая называет путь, и ничего не записывает; переместите или переименуйте проект и запустите команду снова. Пробел или апостроф в пути допустимы.

Для MCP-серверов профиля предусмотрены три рекомендации, каждая из которых называет поле профиля:

Рекомендация об учётных данных никогда не печатает найденное значение. Значение, содержащее ссылку ${...}, никогда не помечается.

Конфигурации оператора с комментариямиCopy Anchor Link

Некоторые конфигурации окружений — это файлы, которые вы также редактируете сами, например settings.json, opencode.json (который может быть в формате JSONC), openclaw.json (JSON5) и config.yaml. Установка объединяет свои ключи с этими файлами и сохраняет каждый ключ, добавленный вами.

Объединение перезаписывает файл как обычный JSON или YAML, что удалило бы комментарии, висячие запятые и синтаксис JSON5. Поэтому:

• Когда объединение не изменило бы ни одного значения (например, вы уже сами добавили ключи Apothem), файл остаётся побайтово неизменным.
• Когда объединение должно изменить значение в файле, который содержит комментарии или синтаксис JSON5, или в файле, который вообще не разбирается, установка ничего не записывает для этого окружения и завершается с кодом 1 и кодом ошибки config.unparseable. Поле fix называет ключи, которые добавила бы установка, чтобы вы могли преобразовать файл в обычный JSON или YAML либо добавить эти ключи вручную и запустить команду повторно.
• Когда ключ, который установка заполняет отображением или списком (например, skills.external_dirs в config.yaml), содержит в вашем файле скалярное значение или контейнер другой формы, установка ничего не записывает для этого окружения и завершается с кодом 1 и тем же кодом ошибки, потому что заполнение ключа отбросило бы ваше значение. Ошибка называет ключ; приведите его к названной в ней форме или удалите и запустите команду повторно. Ключ, который вы оставили пустым (skills:, под которым ничего нет), заполняется.

ПараметрыCopy Anchor Link

Вывод JSONCopy Anchor Link

Когда указан --json (или --format json), в stdout записывается один документ JSON:

{
  "schema_version": 1,
  "status": "success",
  "command": "install",
  "action": "installed",
  "harness": "claude-code",
  "profile_path": "C:\\Users\\Example\\.config\\apothem\\profile.yaml",
  "project": null,
  "files_written": ["C:\\Users\\Example\\.claude\\settings.json"],
  "results": [],
  "warnings": [],
  "error": null,
  "output_path": "C:\\Users\\Example\\.claude\\settings.json"
}

Для --dry-run ничего не записывается, а results перечисляет каждый путь, который записала бы установка, — каждый с результатом, который у него был бы (created, updated или unchanged), а для файла, который вы также редактируете сами, — с унифицированным diff в detail.diff; это тот же план, который показывает apothem diff:

{
  "schema_version": 1,
  "status": "dry_run",
  "command": "install",
  "action": "dry_run",
  "harness": "claude-code",
  "files_written": [],
  "results": [
    {
      "harness": "claude-code",
      "outcome": "created",
      "operation": "write_text",
      "path": "C:\\Users\\Example\\.claude\\settings.json",
      "message": "dry run: no filesystem changes made"
    }
  ],
  "warnings": [],
  "error": null
}

Когда указан --clean, конверт дополнительно содержит объект clean, описывающий фазу удаления, — список решений по каждой цели, был ли запуск предпросмотром, и каталог резервной копии с временной меткой (null в пробном запуске):

{
  "clean": {
    "dry_run": true,
    "backup_dir": null,
    "targets": [
      {
        "path": "C:\\Users\\Example\\.claude",
        "present": true,
        "removed": false,
        "skipped_reason": null
      }
    ]
  }
}

Пробный запуск с очисткой показывает предпросмотр обеих фаз в одном документе: предпросмотр удаления в clean и предпросмотр новых записей в results.

Ожидаемые ошибки проверки используют тот же конверт и включают объект ошибки:

{
  "schema_version": 1,
  "status": "error",
  "command": "install",
  "harness": "all",
  "files_written": [],
  "error": {
    "code": "project.required",
    "field": "project",
    "reason": "project-scope harnesses require --project: cursor, gemini-cli, github-copilot, kimi-code, windsurf, codebuddy, kiro, trae, zed, glm.",
    "fix": "Pass --project PATH or select only user-scope harnesses."
  }
}

ПримерыCopy Anchor Link

apothem install --harness claude-code
apothem install --harness claude-code --dry-run
apothem install --harness cursor --project . --profile ~/profile.yaml --json
apothem install --harness all --project . --dry-run --json
apothem installing --harness claude-code   # continuous-form alias
apothem Installing --harness claude-code   # capitalized variant

Коды выходаCopy Anchor Link

См. такжеCopy Anchor Link

• apothem installing — псевдоним этой команды в продолженной форме (документирован здесь; CLI принимает обе формы)
• apothem update — повторно применить текущий профиль к окружению
• apothem verify — подтвердить, что адаптер активен
• Начало работы — полное руководство по установке