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에서는 이 생성이 "operation": "profile_created"가 담긴 warnings 항목으로 보고됩니다.

• --dry-run은 절대 프로필을 쓰지 않습니다. 미리보기는 메모리 안의 스타터 프로필을 사용하며 "operation": "profile_scaffold_preview"를 보고합니다.
• 명시적으로 지정한 --profile PATH가 존재하지 않으면 절대 생성되지 않습니다. 명령은 profile.not_found와 함께 1로 종료합니다.

영향 범위 미리보기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 폴더에 쓰인 뒤 완료되면 제자리로 이름이 바뀌므로, 실패하거나 중단된 쓰기가 최종 이름으로 반쯤 쓰인 스킬 폴더를 남기는 일은 없습니다. 마무리하려면 설치를 다시 실행하세요. 남아 있는 스테이징 폴더는 교체됩니다.
• 이 폴더들 중 하나 또는 그 상위에 있는 심볼릭 링크(도트파일 관리자가 ~/.config나 ~/.agents에 만드는 것처럼)는 홈 디렉터리 안의 어딘가로 이어질 때 따라갑니다. 홈 디렉터리를 벗어나는 링크는 target escapes the allowed materialization root와 함께 설치를 중단시키며, 스킬 폴더 안의 링크도 마찬가지입니다.
• 설치는 저장소에 스킬 파일이나 규칙 파일을 추가하지 않습니다. 프로젝트에는 어댑터의 규칙 파일과, 모든 프로젝트 설치가 만드는 .apothem/ 데이터 폴더가 생깁니다.
• Apothem 스킬의 이름을 가졌지만 Apothem이 쓰지 않은 스킬 폴더는 건너뜁니다. 설치는 Warning: 줄을 출력하고, --format json 봉투는 그 폴더의 이름을 알려 주는 "outcome": "warning"과 "operation": "skill_conflict"가 담긴 warnings 항목을 담습니다. 폴더의 이름을 바꾸거나 옮긴 다음 update를 실행하세요.
• 이러한 모든 설치, 업데이트, 드라이 런은 --project 바깥에 쓰는 폴더의 이름을 알려 주는 Note:를 출력합니다. JSON 봉투에서는 "operation": "user_level_write"와 paths 목록이 담긴 warnings 항목입니다.

기능 참고 사항Copy Anchor Link

각 어댑터는 해당 하니스가 네이티브로 지원하는 기능만 투영합니다. 네이티브 표면이 없는 기능은 조용히 버려지지 않고 보고됩니다. plain 모드에서는 하니스당 하나의 묶인 참고로 표시됩니다(예: Note: <harness> - 9 capabilities not projected; pass --verbose for detail). --verbose에서는 각 기능이 자체 근거 줄을 출력합니다. 그 밖의 어댑터 경고도 plain 모드에서 각자의 Warning: 줄에 출력됩니다. 예를 들어 새 .rules가 가리는 지침 파일의 이름을 알려 주는 Zed 경고가 그렇습니다. --format json 봉투는 상세 수준과 관계없이 항상 전체 warnings 배열을 담습니다.

설치와 업데이트는 권고도 Note: 줄로 출력합니다. 권고는 설치가 쓰는 내용을 절대 바꾸지 않습니다. 설치가 공유 루트, 즉 다른 도구도 로드하는 경로(예: 스킬 폴더 ~/.agents/skills/)에 쓰는 경우, 참고는 그 도구들의 이름을 알려 주며, 특정 조건에서만 그 경로를 로드하는 도구는 괄호 안에 넣습니다. 예를 들어 Open-Claw (only under its default state directory)가 그렇습니다. 다른 설치도 쓰는 폴더에 쓰는 설치(holder 역할)는 그 폴더를 사용하는 마지막 Apothem 설치가 제거될 때까지 폴더가 남는다고 알리고, 지금 그 폴더를 사용하는 설치들의 이름을 알려 줍니다. 설치 대상 도구가 이미 다른 설치의 공유 루트에서 Apothem 콘텐츠를 로드하고 있는 경우, 참고는 그것을 배치한 설치의 이름을 알려 줍니다. 등록된 소유자가 아직 그 폴더를 사용하면 그 소유자를, 그렇지 않으면 그 폴더를 사용하는 가장 오래된 설치를 알려 줍니다. --format json 봉투에서 각 권고는 "outcome": "advisory"와 "operation": "shared_root"가 담긴 warnings 항목입니다. 그 role은 owner, holder, 또는 reader이고, holders는 그 폴더를 사용하는 설치들을 나열하며, owner_of_record는 기록상의 소유자를 알려 줍니다.

훅을 등록하는 설치는 훅 파일에 관한 참고도 출력합니다. hook_review 권고는 도구가 훅을 실행하기 전에 필요한 단계(재시작과 검토, 또는 워크스페이스 신뢰)의 이름을 알려 주거나, 저장소가 커밋하며 이 머신의 인터프리터를 명시하는 훅 파일의 위험을 알려 줍니다. hook_import 권고는 Claude Code의 설정 파일(예: Claude Code용 Apothem 설치가 쓰는 파일)에 있는 훅도 실행하는 도구에 대해 나타나며, 그 가져오기를 끄는 도구 자체의 스위치와 그 스위치가 함께 중단시키는 것을 알려 줍니다. 각각은 "outcome": "advisory", harness, 훅 파일의 path, 그리고 message가 담긴 warnings 항목입니다.

훅 명령은 프로젝트 경로와 인터프리터 경로를 큰따옴표 안에 담으며, 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 구문을 담은 파일, 또는 아예 파싱되지 않는 파일에서 병합이 값을 바꿔야 하는 경우, 설치는 해당 하니스에 대해 아무것도 쓰지 않고 오류 코드 config.unparseable과 함께 1로 종료합니다. fix 필드는 설치가 추가할 키의 이름을 알려 주므로, 파일을 일반 JSON 또는 YAML로 변환하거나, 그 키들을 직접 추가한 다음 다시 실행할 수 있습니다.
• 설치가 매핑이나 목록으로 채우는 키(예: config.yaml의 skills.external_dirs)가 파일에서 스칼라 값이나 다른 컨테이너 형태를 담고 있으면, 설치는 해당 하니스에 대해 아무것도 쓰지 않고 같은 오류 코드와 함께 1로 종료합니다. 그 키를 채우면 여러분의 값이 버려지기 때문입니다. 오류는 키의 이름을 알려 줍니다. 키를 오류가 알려 주는 형태로 바꾸거나 제거한 다음 다시 실행하세요. 비워 둔 키(아래에 아무것도 없는 skills:)는 채워집니다.

옵션Copy Anchor Link

JSON 출력Copy Anchor Link

--json(또는 --format json)을 지정하면, 하나의 JSON 문서가 stdout에 쓰입니다.

{
  "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)가 함께 표시되고, 여러분도 직접 편집하는 파일의 경우 detail.diff에 통합 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 — 어댑터가 활성 상태인지 확인
• 시작하기 — 전체 설치 가이드