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 ルートの下に書き込み、ユーザースコープのアダプターは、そのルートの外側にあるホームディレクトリの下に書き込みます。インストールがいずれかのファイルを書き込む前に、コマンドは具体的なターゲットを 2 つの見出しの下にグループ化して出力します。プロジェクトルートの内側にあるものと、ホームディレクトリの下にあるものです。3 つ目の見出しには、プロジェクトスコープのアダプターが --project の外側に書き込む、ホームディレクトリ内の共有フォルダーが列挙されます。スキルフォルダーと ~/.config/apothem/ です（ホームディレクトリ内のフォルダー を参照）。唯一の例外は --clean です。そのクリーンスレート手順は、このプレビューより前に実行され、以下で説明するとおりバックアップを書き込み、既存のターゲットを削除します。

選択内容がプロジェクトルートの外に書き込む場合、それがホームを基点とするアダプターのフォルダーであっても共有フォルダーであっても、対話的な確認がホームを基点とする書き込みを保護します。--yes、非対話シェル（TTY なし）、--dry-run、--format json は、それぞれ確認を求めずに続行します。何も書き込まないのは --dry-run だけです。--format json はプレビューと確認プロンプトを省略しますが、書き込みは実行します。ホームディレクトリのプロンプトを拒否すると、インストールの書き込みより前に中止します。--clean を指定すると、まずクリーンスレートの手順が、対象ごとの確認を伴って実行されます。この手順は ~/.apothem/backups の下にバックアップを書き込み、確認された対象を削除します。インストールのプロンプトを拒否した場合でも、それらの削除とバックアップはそのまま残ります。

ホームディレクトリ内のフォルダーCopy Anchor Link

7 つのプロジェクトスコープのアダプターは、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 を指定したインストールは、同じフォルダーに書き込みます。
• あるフォルダーを対象とするインストールは、どれも同じファイルを書き込みます。2 回目のインストールはそれらを見つけて 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 モードでは、これはハーネスごとに 1 つのグループ化された注記になります（例: 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 サーバーには 3 つの勧告があり、それぞれが該当するプロファイルフィールドの名前を挙げます。

認証情報の勧告が、検出した値を出力することは決してありません。 ${...} 参照を含む値にフラグが立てられることは決してありません。

コメントを含むオペレーターの設定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 の統一差分が付きます。これは 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
      }
    ]
  }
}

クリーンスレートのドライランは、両方のフェーズを 1 つのドキュメントでプレビューします。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 — アダプターが有効であることを確認する
• はじめに — 完全なインストールガイド