install

Memasang konfigurasi adapter harness dari profil bersama.

RingkasanCopy 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]

Memuat dan memvalidasi profil bersama, memilih adapter bernama atau himpunan all selingkup registri, memvalidasi rencana materialisasi, lalu menulis konfigurasi native-harness beserta kohor pendukung. Adapter berlingkup-proyek memerlukan --project PATH.

Alias bentuk-kontinu apothem installing (juga diterima sebagai apothem Installing) di-resolve ke handler yang sama.

Eksekusi pertama tanpa profilCopy Anchor Link

Ketika --profile dihilangkan dan tidak ada profil di jalur default (~/.config/apothem/profile.yaml), install terlebih dahulu menulis profil awal di sana, mencetak Created a starter profile at <path>, lalu melanjutkan. Profil awal membawa bidang identitas placeholder, sehingga pemasangan juga mencetak catatan identitas-placeholder; personalisasikan profil, lalu jalankan update untuk menerapkannya. Di bawah --json, pembuatan ini dilaporkan sebagai entri warnings dengan "operation": "profile_created".

• --dry-run tidak pernah menulis profil: pratinjau menggunakan profil awal di memori dan melaporkan "operation": "profile_scaffold_preview".
• --profile PATH eksplisit yang tidak ada tidak pernah dibuat; perintah keluar dengan kode 1 disertai profile.not_found.

Pratinjau radius-dampakCopy Anchor Link

install --harness all menyebar ke cakupan campuran: adapter berlingkup-proyek menulis di bawah root --project yang diberikan, sedangkan adapter berlingkup-pengguna menulis di bawah direktori home Anda — di luar root tersebut. Sebelum pemasangan menulis berkas apa pun, perintah ini mencetak target konkret yang dikelompokkan di bawah dua judul: yang berada di dalam root proyek dan yang berada di bawah direktori home Anda. Judul ketiga mencantumkan folder bersama di direktori home Anda yang ditulis oleh adapter berlingkup-proyek, di luar --project: folder skill dan ~/.config/apothem/ (lihat Folder di direktori home Anda). Satu-satunya pengecualian adalah --clean: langkah pembersihan menyeluruh berjalan sebelum pratinjau ini, menulis cadangan dan menghapus target sebelumnya, sebagaimana dijelaskan di bawah.

Ketika pilihan tersebut menulis di luar root proyek, baik ke folder milik adapter yang berakar di direktori home maupun ke folder bersama, sebuah konfirmasi interaktif menjaga penulisan yang berakar di direktori home. --yes, shell non-interaktif (tanpa TTY), --dry-run, dan --format json masing-masing melanjutkan tanpa meminta konfirmasi. Hanya --dry-run yang tidak menulis apa pun; --format json melewati pratinjau dan prompt konfirmasi tetapi tetap melakukan penulisan. Menolak prompt direktori home membatalkan proses sebelum pemasangan menulis. Dengan --clean, langkah awal bersih dijalankan lebih dulu di bawah konfirmasi per target tersendiri: langkah itu menulis cadangan di bawah ~/.apothem/backups dan menghapus target yang dikonfirmasinya. Penghapusan tersebut dan cadangannya tetap berada di tempatnya ketika prompt pemasangan ditolak.

Folder di direktori home AndaCopy Anchor Link

Tujuh adapter berlingkup-proyek menulis skill Apothem, beserta aturan dan templat yang dirujuk oleh skill tersebut, ke folder di direktori home pengguna Anda:

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 memilih berkas aturan dan proyek tempat pemasangan tersebut berada. Opsi ini tidak mengubah ke mana skill ditulis: pemasangan dengan --project A dan pemasangan dengan --project B menulis folder yang sama.
• Setiap pemasangan yang menyebutkan sebuah folder menulis berkas yang sama. Pemasangan kedua menemukannya dan melaporkan unchanged, dan urutan pemasangan Anda tidak berpengaruh.
• Folder home ditulis sebelum apa pun di dalam proyek. Jika penulisan di sana gagal, pemasangan adapter berhenti dengan galat tersebut dan proyek tidak berubah. Galat menyebutkan jalur yang menghalangi, misalnya berkas bernama ~/.agents di tempat yang seharusnya berupa folder.
• Setiap folder skill ditulis ke folder tersembunyi .<name>.apothem-staging di sebelahnya dan diganti namanya ke tempatnya setelah lengkap, sehingga penulisan yang gagal atau terputus tidak pernah meninggalkan folder skill setengah jadi dengan nama akhirnya. Jalankan pemasangan lagi untuk menyelesaikannya; pemasangan itu menggantikan folder staging yang tersisa.
• Symlink pada atau di atas salah satu folder ini, seperti yang dibuat oleh pengelola dotfile untuk ~/.config atau ~/.agents, diikuti ketika mengarah ke suatu tempat di dalam direktori home Anda. Tautan yang keluar dari direktori home Anda menghentikan pemasangan dengan target escapes the allowed materialization root, demikian pula tautan di dalam folder skill.
• Pemasangan tidak menambahkan berkas skill atau aturan apa pun ke repositori Anda. Proyek mendapatkan berkas aturan adapter, ditambah folder data .apothem/ yang dibuat oleh setiap pemasangan proyek.
• Folder skill yang memiliki nama skill Apothem dan tidak ditulis oleh Apothem dilewati. Pemasangan mencetak baris Warning: dan amplop --format json membawa entri warnings dengan "outcome": "warning" dan "operation": "skill_conflict" yang menyebutkan folder tersebut. Ganti nama atau pindahkan folder itu, lalu jalankan update.
• Setiap pemasangan, update, dan dry run semacam itu mencetak Note: yang menyebutkan folder yang ditulisnya di luar --project. Dalam amplop JSON, catatan ini berupa entri warnings dengan "operation": "user_level_write" dan daftar paths.

Catatan kemampuanCopy Anchor Link

Setiap adapter hanya memproyeksikan kemampuan yang didukung secara native oleh harness-nya; kemampuan tanpa permukaan native dilaporkan, bukan dibuang diam-diam. Dalam mode plain, ini berupa satu catatan terkelompok per harness (misalnya Note: <harness> - 9 capabilities not projected; pass --verbose for detail); di bawah --verbose, setiap kemampuan mencetak baris alasannya sendiri. Peringatan adapter lainnya juga dicetak pada baris Warning: tersendiri dalam mode plain, misalnya peringatan Zed yang menyebutkan berkas instruksi yang disembunyikan oleh .rules yang baru. Amplop --format json selalu membawa larik warnings lengkap terlepas dari tingkat verbositas.

Perintah install dan update juga mencetak pemberitahuan sebagai baris Note:. Sebuah pemberitahuan tidak pernah mengubah apa yang ditulis pemasangan. Ketika sebuah pemasangan menulis root bersama, yaitu jalur yang juga dimuat oleh alat lain (misalnya folder skill ~/.agents/skills/), catatan tersebut menyebutkan alat-alat itu, dan menempatkan alat yang memuat jalur tersebut hanya dalam kondisi tertentu di dalam tanda kurung, misalnya Open-Claw (only under its default state directory). Pemasangan yang menulis folder yang juga ditulis oleh pemasangan lain (peran holder) menyatakan bahwa folder tersebut tetap ada sampai pemasangan Apothem terakhir yang menggunakannya dicopot, dan menyebutkan pemasangan yang menggunakannya saat ini. Ketika sebuah pemasangan menargetkan alat yang sudah memuat konten Apothem dari root bersama milik pemasangan lain, catatan tersebut menyebutkan pemasangan yang menempatkannya: pemilik terdaftar selama pemilik itu masih menggunakan folder tersebut, atau jika tidak, pemasangan tertua yang menggunakannya. Dalam amplop --format json, setiap pemberitahuan adalah entri warnings dengan "outcome": "advisory" dan "operation": "shared_root"; role-nya adalah owner, holder, atau reader, holders mencantumkan pemasangan yang menggunakan folder tersebut, dan owner_of_record menyebutkan pemilik tercatat.

Pemasangan yang mendaftarkan hook juga mencetak catatan tentang berkas hook. Pemberitahuan hook_review menyebutkan langkah yang dibutuhkan alat sebelum menjalankan hook (memulai ulang dan meninjau, atau memercayai workspace), atau bahaya dari berkas hook yang di-commit oleh sebuah repositori dan menyebutkan interpreter mesin ini. Pemberitahuan hook_import muncul untuk alat yang juga menjalankan hook di berkas pengaturan Claude Code, seperti yang ditulis oleh pemasangan Apothem untuk Claude Code, dan menyebutkan sakelar milik alat itu sendiri untuk mematikan impor tersebut serta apa saja yang juga dihentikan oleh sakelar itu. Masing-masing adalah entri warnings dengan "outcome": "advisory", harness, path berkas hook, dan sebuah message.

Perintah hook memuat jalur proyek dan jalur interpreter di dalam tanda kutip ganda, yang dibaca oleh sh, Git Bash, dan PowerShell. Jalur yang berisi $, backtick, tanda kutip ganda, atau backslash akan membuat perintah menjalankan berkas lain, sehingga pemasangan (dan --dry-run) berhenti dengan galat yang menyebutkan jalur tersebut dan tidak menulis apa pun; pindahkan atau ganti nama proyek lalu jalankan lagi. Spasi atau apostrof dalam jalur tidak menjadi masalah.

Server MCP pada profil mendapatkan tiga pemberitahuan, masing-masing menyebutkan bidang profil yang bersangkutan:

Pemberitahuan kredensial tidak pernah mencetak nilai yang ditemukannya. Nilai yang berisi referensi ${...} tidak pernah ditandai.

Konfigurasi operator dengan komentarCopy Anchor Link

Beberapa konfigurasi harness adalah berkas yang juga Anda sunting, seperti settings.json, opencode.json (yang mungkin berupa JSONC), openclaw.json (JSON5), dan config.yaml. Pemasangan menggabungkan kuncinya ke dalam berkas-berkas ini dan mempertahankan setiap kunci yang Anda tambahkan.

Penggabungan menulis ulang berkas sebagai JSON atau YAML biasa, yang akan membuang komentar, koma di akhir, dan sintaks JSON5. Oleh karena itu:

• Ketika penggabungan tidak akan mengubah nilai apa pun (misalnya, Anda sudah menambahkan sendiri kunci-kunci Apothem), berkas dibiarkan apa adanya, byte demi byte.
• Ketika penggabungan harus mengubah sebuah nilai dalam berkas yang membawa komentar atau sintaks JSON5, atau dalam berkas yang sama sekali tidak dapat di-parse, pemasangan tidak menulis apa pun untuk harness tersebut dan keluar dengan kode 1 serta kode galat config.unparseable. Bidang fix menyebutkan kunci yang akan ditambahkan pemasangan, sehingga Anda dapat mengonversi berkas ke JSON atau YAML biasa, atau menambahkan kunci tersebut secara manual lalu menjalankan ulang.
• Ketika kunci yang diisi pemasangan dengan mapping atau list (misalnya skills.external_dirs di config.yaml) berisi nilai skalar, atau bentuk kontainer yang lain, dalam berkas Anda, pemasangan tidak menulis apa pun untuk harness tersebut dan keluar dengan kode 1 serta kode galat yang sama, karena mengisi kunci itu akan membuang nilai Anda. Galat menyebutkan kunci tersebut; ubah ke bentuk yang disebutkannya, atau hapus, lalu jalankan ulang. Kunci yang Anda biarkan kosong (skills: tanpa isi di bawahnya) akan diisi.

OpsiCopy Anchor Link

Keluaran JSONCopy Anchor Link

Ketika --json (atau --format json) diberikan, satu dokumen JSON ditulis ke 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"
}

Untuk --dry-run, tidak ada yang ditulis dan results mencantumkan setiap jalur yang akan ditulis pemasangan, masing-masing dengan hasil yang akan diperolehnya (created, updated, atau unchanged) dan, untuk berkas yang juga Anda sunting, diff terpadu di detail.diff — rencana yang sama dengan yang ditampilkan 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
}

Ketika --clean diberikan, amplop juga membawa objek clean yang menjelaskan fase penghapusan — daftar disposisi per target, apakah eksekusi tersebut merupakan pratinjau, dan direktori cadangan bercap waktu (null dalam dry run):

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

Dry run awal bersih mempratinjau kedua fase dalam satu dokumen: pratinjau penghapusan di bawah clean dan pratinjau penulisan baru di bawah results.

Galat validasi yang diharapkan menggunakan amplop yang sama dan menyertakan objek galat:

{
  "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."
  }
}

ContohCopy 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

Kode keluarCopy Anchor Link

Lihat jugaCopy Anchor Link

• apothem installing — alias bentuk-kontinu untuk perintah ini (didokumentasikan di sini; CLI menerima kedua bentuk)
• apothem update — menerapkan ulang profil saat ini ke sebuah harness
• apothem verify — memastikan adapter aktif
• Memulai — panduan pemasangan lengkap