install

Installiert eine Harness-Adapterkonfiguration aus dem gemeinsamen Profil.

ÜbersichtCopy 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]

Lädt und validiert das gemeinsame Profil, wählt einen benannten Adapter oder die registry-weite Menge all aus, validiert den Materialisierungsplan und schreibt die harness-native Konfiguration sowie die Unterstützungskohorten. Adapter mit Projekt-Geltungsbereich erfordern --project PATH.

Der Alias in Verlaufsform apothem installing (auch als apothem Installing akzeptiert) wird auf denselben Handler aufgelöst.

Erster Lauf ohne ProfilCopy Anchor Link

Wenn --profile weggelassen wird und am Standardpfad (~/.config/apothem/profile.yaml) kein Profil existiert, schreibt install zuerst das Starterprofil dorthin, gibt Created a starter profile at <path> aus und fährt fort. Das Starterprofil trägt Platzhalter-Identitätsfelder, daher gibt die Installation auch den Hinweis zur Platzhalter-Identität aus; passen Sie das Profil an und führen Sie dann update aus, um es anzuwenden. Unter --json wird das Anlegen als warnings-Eintrag mit "operation": "profile_created" gemeldet.

• --dry-run schreibt das Profil niemals: Die Vorschau verwendet das Starterprofil im Speicher und meldet "operation": "profile_scaffold_preview".
• Ein explizit angegebener --profile PATH, der nicht existiert, wird niemals angelegt; der Befehl endet mit Exit-Code 1 und profile.not_found.

Wirkungsradius-VorschauCopy Anchor Link

install --harness all fächert sich in gemischte Geltungsbereiche auf: Adapter mit Projekt-Geltungsbereich schreiben unter die angegebene --project-Wurzel, während Adapter mit Benutzer-Geltungsbereich unter Ihr Home-Verzeichnis schreiben — außerhalb dieser Wurzel. Bevor die Installation eine Datei schreibt, gibt der Befehl die konkreten Ziele aus, gruppiert unter zwei Überschriften: die Ziele innerhalb der Projektwurzel und die Ziele unter Ihrem Home-Verzeichnis. Eine dritte Überschrift listet die gemeinsamen Ordner in Ihrem Home-Verzeichnis auf, die die Adapter mit Projekt-Geltungsbereich außerhalb von --project schreiben: den Skills-Ordner und ~/.config/apothem/ (siehe Ordner in Ihrem Home-Verzeichnis). Die einzige Ausnahme ist --clean: Sein Schritt für einen sauberen Neuanfang läuft vor dieser Vorschau, schreibt eine Sicherung und entfernt vorherige Ziele, wie unten beschrieben.

Wenn die Auswahl außerhalb der Projektwurzel schreibt, sei es in den Ordner eines Adapters im Home-Verzeichnis oder in einen gemeinsamen Ordner, schützt eine interaktive Bestätigung die Schreibvorgänge im Home-Verzeichnis. --yes, eine nicht interaktive Shell (kein TTY), --dry-run und --format json fahren jeweils ohne Nachfrage fort. Nur --dry-run schreibt nichts; --format json überspringt die Vorschau und die Bestätigungsabfrage, führt die Schreibvorgänge aber dennoch aus. Lehnen Sie die Abfrage zum Home-Verzeichnis ab, bricht die Installation ab, bevor sie schreibt. Mit --clean läuft der Schritt für den sauberen Neuanfang zuerst, mit einer eigenen Bestätigung pro Ziel: Er schreibt eine Sicherung unter ~/.apothem/backups und entfernt die Ziele, die Sie bestätigen. Diese Entfernungen und die Sicherung bleiben bestehen, wenn die Installationsabfrage abgelehnt wird.

Ordner in Ihrem Home-VerzeichnisCopy Anchor Link

Sieben Adapter mit Projekt-Geltungsbereich schreiben Apothems Skills sowie die Regeln und Vorlagen, auf die sich die Skills beziehen, in Ordner in Ihrem Benutzer-Home:

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 wählt die Regeldatei und das Projekt aus, zu dem die Installation gehört. Es ändert nicht, wohin die Skills gehen: Eine Installation mit --project A und eine mit --project B schreiben dieselben Ordner.
• Jede Installation, die einen Ordner benennt, schreibt dieselben Dateien. Eine zweite Installation findet sie vor und meldet unchanged, und die Reihenfolge, in der Sie installieren, spielt keine Rolle.
• Die Home-Ordner werden vor allem anderen im Projekt geschrieben. Schlägt dort ein Schreibvorgang fehl, bricht die Installation des Adapters mit dem Fehler ab, und das Projekt bleibt unverändert. Der Fehler benennt den Pfad, der im Weg ist, zum Beispiel eine Datei namens ~/.agents dort, wo der Ordner hingehört.
• Jeder Skill-Ordner wird in einen versteckten Ordner .<name>.apothem-staging daneben geschrieben und nach Abschluss an seinen Platz umbenannt, sodass ein fehlgeschlagener oder unterbrochener Schreibvorgang niemals einen halb geschriebenen Skill-Ordner unter seinem endgültigen Namen hinterlässt. Führen Sie die Installation erneut aus, um sie abzuschließen; sie ersetzt einen übrig gebliebenen Staging-Ordner.
• Ein symbolischer Link auf oder oberhalb eines dieser Ordner, wie ihn Dotfile-Manager für ~/.config oder ~/.agents anlegen, wird verfolgt, wenn er an eine Stelle innerhalb Ihres Home-Verzeichnisses führt. Ein Link, der Ihr Home-Verzeichnis verlässt, bricht die Installation mit target escapes the allowed materialization root ab, ebenso ein Link innerhalb eines Skill-Ordners.
• Die Installation fügt Ihrem Repository keine Skill- oder Regeldatei hinzu. Das Projekt erhält die Regeldatei des Adapters sowie den Datenordner .apothem/, den jede Projektinstallation anlegt.
• Ein Skill-Ordner, der den Namen eines Apothem-Skills trägt und den Apothem nicht geschrieben hat, wird übersprungen. Die Installation gibt eine Warning:-Zeile aus, und der --format json-Umschlag trägt einen warnings-Eintrag mit "outcome": "warning" und "operation": "skill_conflict", der den Ordner benennt. Benennen Sie den Ordner um oder verschieben Sie ihn und führen Sie dann update aus.
• Jede solche Installation, Aktualisierung und jeder solche Dry-Run gibt einen Note: aus, der die Ordner benennt, die außerhalb von --project geschrieben werden. Im JSON-Umschlag ist er ein warnings-Eintrag mit "operation": "user_level_write" und einer paths-Liste.

Hinweise zu FähigkeitenCopy Anchor Link

Jeder Adapter projiziert nur die Fähigkeiten, die sein Harness nativ unterstützt; Fähigkeiten ohne native Oberfläche werden gemeldet, nicht still verworfen. Im Plain-Modus ist dies ein einzelner gruppierter Hinweis je Harness (zum Beispiel Note: <harness> - 9 capabilities not projected; pass --verbose for detail); unter --verbose gibt jede Fähigkeit ihre eigene Begründungszeile aus. Jede andere Adapterwarnung wird auch im Plain-Modus in einer eigenen Warning:-Zeile ausgegeben, zum Beispiel die Zed-Warnung, die eine Anweisungsdatei benennt, die von der neuen .rules-Datei verdeckt wird. Der --format json-Umschlag trägt unabhängig von der Ausführlichkeit immer das vollständige warnings-Array.

Installation und Aktualisierung geben außerdem Empfehlungshinweise als Note:-Zeilen aus. Ein Empfehlungshinweis ändert niemals, was die Installation schreibt. Wenn eine Installation in ein gemeinsames Wurzelverzeichnis schreibt, also einen Pfad, den auch andere Werkzeuge laden (zum Beispiel den Skills-Ordner ~/.agents/skills/), benennt der Hinweis diese Werkzeuge und setzt ein Werkzeug, das den Pfad nur unter einer Bedingung lädt, in Klammern, zum Beispiel Open-Claw (only under its default state directory). Eine Installation, die einen Ordner schreibt, den auch andere Installationen schreiben (die Rolle holder), teilt mit, dass der Ordner bestehen bleibt, bis die letzte Apothem-Installation, die ihn verwendet, deinstalliert wird, und benennt die Installationen, die ihn derzeit verwenden. Wenn eine Installation auf ein Werkzeug zielt, das bereits Apothem-Inhalte aus dem gemeinsamen Wurzelverzeichnis einer anderen Installation lädt, benennt der Hinweis die Installation, die sie dort abgelegt hat: den registrierten Eigentümer, solange er den Ordner noch verwendet, andernfalls die älteste Installation, die ihn verwendet. Im --format json-Umschlag ist jeder Empfehlungshinweis ein warnings-Eintrag mit "outcome": "advisory" und "operation": "shared_root"; seine role ist owner, holder oder reader, holders listet die Installationen auf, die den Ordner verwenden, und owner_of_record benennt den eingetragenen Eigentümer.

Eine Installation, die Hooks registriert, gibt außerdem Hinweise zur Hook-Datei aus. Ein hook_review-Empfehlungshinweis benennt den Schritt, den das Werkzeug benötigt, bevor es die Hooks ausführt (einen Neustart und eine Überprüfung oder das Vertrauen in den Arbeitsbereich), oder die Gefahr einer Hook-Datei, die ein Repository eincheckt und die den Interpreter dieses Rechners benennt. Ein hook_import-Empfehlungshinweis erscheint für ein Werkzeug, das auch die Hooks in den Einstellungsdateien von Claude Code ausführt, etwa denen, die die Apothem-Installation für Claude Code schreibt, und benennt den eigenen Schalter des Werkzeugs, mit dem sich dieser Import abschalten lässt, sowie das, was der Schalter außerdem unterbindet. Jeder ist ein warnings-Eintrag mit "outcome": "advisory", dem harness, dem path der Hook-Datei und einer message.

Ein Hook-Befehl setzt den Projektpfad und den Interpreterpfad in doppelte Anführungszeichen, die sh, Git Bash und PowerShell jeweils lesen. Ein Pfad, der $, einen Backtick, ein doppeltes Anführungszeichen oder einen Backslash enthält, würde den Befehl eine andere Datei ausführen lassen; daher bricht die Installation (und --dry-run) mit einem Fehler ab, der den Pfad benennt, und schreibt nichts; verschieben oder benennen Sie das Projekt um und führen Sie den Befehl erneut aus. Ein Leerzeichen oder ein Apostroph in einem Pfad ist unproblematisch.

Die MCP-Server des Profils erhalten drei Empfehlungshinweise, die jeweils das Profilfeld benennen:

Der Empfehlungshinweis zu Anmeldedaten gibt niemals den gefundenen Wert aus. Ein Wert, der eine ${...}-Referenz enthält, wird niemals markiert.

Operator-Konfigurationen mit KommentarenCopy Anchor Link

Manche Harness-Konfigurationen sind Dateien, die Sie ebenfalls bearbeiten, etwa settings.json, opencode.json (das JSONC sein kann), openclaw.json (JSON5) und config.yaml. Die Installation führt ihre Schlüssel in diese Dateien zusammen und behält jeden Schlüssel bei, den Sie hinzugefügt haben.

Eine Zusammenführung schreibt die Datei als reines JSON oder YAML neu, wodurch Kommentare, nachgestellte Kommas und JSON5-Syntax verloren gingen. Daher gilt:

• Wenn die Zusammenführung keinen Wert ändern würde (zum Beispiel, weil Sie Apothems Schlüssel bereits selbst hinzugefügt haben), bleibt die Datei Byte für Byte unverändert.
• Wenn die Zusammenführung einen Wert in einer Datei ändern muss, die Kommentare oder JSON5-Syntax enthält, oder in einer Datei, die sich überhaupt nicht parsen lässt, schreibt die Installation für diesen Harness nichts und endet mit Exit-Code 1 und dem Fehlercode config.unparseable. Das Feld fix benennt die Schlüssel, die die Installation hinzufügen würde, sodass Sie die Datei in reines JSON oder YAML umwandeln oder diese Schlüssel von Hand hinzufügen und den Befehl erneut ausführen können.
• Wenn ein Schlüssel, den die Installation mit einer Zuordnung oder einer Liste füllt (zum Beispiel skills.external_dirs in config.yaml), in Ihrer Datei einen skalaren Wert oder die jeweils andere Containerform enthält, schreibt die Installation für diesen Harness nichts und endet mit Exit-Code 1 und demselben Fehlercode, weil das Füllen des Schlüssels Ihren Wert verwerfen würde. Der Fehler benennt den Schlüssel; ändern Sie ihn in die genannte Form oder entfernen Sie ihn und führen Sie den Befehl erneut aus. Ein Schlüssel, den Sie leer gelassen haben (skills: ohne etwas darunter), wird gefüllt.

OptionenCopy Anchor Link

JSON-AusgabeCopy Anchor Link

Wenn --json (oder --format json) angegeben wird, wird ein einzelnes JSON-Dokument nach stdout geschrieben:

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

Bei --dry-run wird nichts geschrieben, und results listet jeden Pfad auf, den die Installation schreiben würde, jeweils mit dem Ergebnis, das sie hätte (created, updated oder unchanged), und, für eine Datei, die Sie ebenfalls bearbeiten, mit dem Unified Diff in detail.diff — derselbe Plan, den apothem diff anzeigt:

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

Wenn --clean angegeben wird, trägt der Umschlag zusätzlich ein clean-Objekt, das die Entfernungsphase beschreibt — die Liste der Dispositionen je Ziel, ob der Lauf eine Vorschau war, und das mit Zeitstempel versehene Sicherungsverzeichnis (null bei einem Dry-Run):

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

Ein Dry-Run mit sauberem Neuanfang zeigt beide Phasen in einem Dokument in der Vorschau: die Entfernungsvorschau unter clean und die Vorschau der neuen Schreibvorgänge unter results.

Erwartete Validierungsfehler verwenden denselben Umschlag und enthalten ein Fehlerobjekt:

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

BeispieleCopy 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

Exit-CodesCopy Anchor Link

Siehe auchCopy Anchor Link

• apothem installing — Alias in Verlaufsform für diesen Befehl (hier dokumentiert; die CLI akzeptiert beide Formen)
• apothem update — wendet das aktuelle Profil erneut auf einen Harness an
• apothem verify — bestätigt, dass der Adapter aktiv ist
• Erste Schritte — vollständige Installationsanleitung