Prise en main : de zéro à un environnement fonctionnel

Ce tutoriel vous accompagne tout au long de votre première configuration d'Apothem. Vous partez d'une machine sans rien d'installé et terminez avec une configuration d'environnement réelle — générée à partir d'un profil que vous avez rédigé, vérifiée et dont le fonctionnement est confirmé. Comptez environ quinze minutes. Chaque commande ci-dessous est réelle et peut être copiée-collée telle quelle.

À la fin, vous aurez :

1. Installé Apothem à l'aide de l'installateur par script.
2. Édité le profil partagé qui pilote chaque environnement.
3. Matérialisé la configuration native d'un environnement.
4. Vérifié cette configuration et confirmé une première exécution fonctionnelle.

Nous utiliserons Claude Code comme environnement d'exemple tout au long du tutoriel, car c'est celui par défaut de l'installateur. Les mêmes étapes s'appliquent à n'importe quel environnement pris en charge : changez le nom lorsque vous arrivez à la liste des environnements.

Ce qu'il vous faut d'abordCopy Anchor Link

• Un shell de type Unix (macOS, Linux ou WSL). L'installateur PowerShell couvre Windows ; ce tutoriel suit la voie bash.
• Python 3.10 ou plus récent dans votre PATH. Vérifiez avec python3 --version.
• Les deux bibliothèques d'exécution que le moteur importe depuis votre interpréteur : click et rich. Le reste de la pile (pyyaml, jsonschema) est vendorisé dans l'arborescence ; seules ces deux-là doivent donc être importables. Si click ou rich manque, l'installateur s'arrête et affiche la commande d'installation. La commande d'une seule ligne envoie le script à bash par un tube, de sorte qu'elle ne peut pas poser de question ; définissez APOTHEM_AUTO_INSTALL_DEPS=1 (par exemple curl -fsSL https://apothem.ahmedgad.com/install.sh | APOTHEM_AUTO_INSTALL_DEPS=1 bash) ou installez d'abord les deux paquets.

Apothem est distribué sous la forme d'une arborescence source groupée plutôt que d'un paquet publié : il n'y a pas d'étape pip install. L'installateur clone l'arborescence et exécute le moteur directement depuis celle-ci.

Étape 1 — Installer ApothemCopy Anchor Link

Exécutez l'installateur réseau :

curl -fsSL https://apothem.ahmedgad.com/install.sh | bash

L'installateur effectue les étapes suivantes :

1. Vérification des prérequis. L'installateur trouve un véritable interpréteur Python 3.10+ et confirme que les deux bibliothèques d'exécution (click et rich) sont importables. S'il en manque une, il la nomme, s'arrête et affiche la commande d'installation ; définissez APOTHEM_AUTO_INSTALL_DEPS=1 pour installer sans invite, puisqu'une exécution par tube ne peut pas poser de question.
2. Placement des sources. L'arborescence fournie est clonée dans ~/.apothem (modifiable avec la variable d'environnement APOTHEM_HOME). Une nouvelle exécution extrait l'étiquette de publication dans le clone existant au lieu de le dupliquer.
3. Amorçage du profil. Si vous n'avez pas encore de profil, l'installateur copie le profil d'exemple vers ~/.config/apothem/profile.yaml, installe et vérifie Claude Code à partir de ce profil dans la même exécution, et avertit que les champs d'identité sont des valeurs provisoires.

Vous pouvez orienter l'installation avec des variables d'environnement. Celles que vous utiliserez le plus probablement :

# Install a different user-scope harness and name the profile path explicitly.
# Put the variables on the `bash` side of the pipe: a variable placed before
# `curl` reaches only curl, not the installer.
curl -fsSL https://apothem.ahmedgad.com/install.sh | \
  APOTHEM_HARNESS=codex \
  APOTHEM_PROFILE="$HOME/.config/apothem/profile.yaml" \
  bash

L'installateur n'installe que des environnements de portée utilisateur. Installez ensuite un environnement de portée projet, en nommant le projet :

apothem install --harness cursor --project /path/to/project

Les autres variables reconnues sont APOTHEM_REPO et APOTHEM_REF (le dépôt distant à cloner et la ref git à extraire — non définie, elle résout et vérifie la dernière étiquette de publication signée ; définissez une étiquette pour l'épingler, ou main pour la branche mouvante (une branche n'est pas une étiquette signée, elle requiert donc aussi APOTHEM_ALLOW_UNVERIFIED=1)), APOTHEM_ALLOW_UNVERIFIED=1 (rétrograde un échec de vérification de la signature de l'étiquette en simple avertissement, et autorise une ref qui n'est pas une étiquette, comme main), APOTHEM_SOURCE (utilise un checkout local existant au lieu de cloner) et APOTHEM_SKIP_VERIFY=1 (ignore la vérification post-installation, que nous voulons exécuter ; laissez-la donc non définie).

Lorsque l'installateur termine une exécution complète, il affiche une bannière indiquant comment invoquer le moteur. Il place un shim apothem sur votre PATH (POSIX : $HOME/.local/bin ; Windows : %LOCALAPPDATA%\Microsoft\WindowsApps) ; une fois ce répertoire sur PATH, vous exécutez donc le moteur directement :

apothem <command>

Si le shim n'a pas pu être placé — ou si son répertoire n'est pas encore sur PATH — la bannière affiche un repli autonome qui ne nécessite aucun shim :

PYTHONPATH="$HOME/.apothem/src" python3 -m apothem <command>

La suite de ce tutoriel écrit apothem <command> ; si vous utilisez la forme de repli, faites précéder chaque commande du préfixe exact affiché par la bannière de votre installateur.

Étape 2 — Faire du profil le vôtreCopy Anchor Link

Le profil partagé situé à ~/.config/apothem/profile.yaml est la source unique de vérité. Chaque adaptateur d'environnement le lit et en dérive la configuration native de son environnement. Éditez-le une fois, et chaque environnement que vous installez reste cohérent.

Ouvrez-le dans l'éditeur du moteur, ou dans n'importe quel éditeur de texte :

apothem profile edit

Un profil minimal et valide ressemble à ceci :

identity:
  name: "Example User"
preferences:
  style: "concise"
rules:
  - "Validate external input before writing files."

Remplacez le name servant d'espace réservé par le vôtre, et ajoutez toutes les règles que vous voulez voir appliquées par chaque environnement. Gardez des valeurs d'exemple fictives : le profil est conçu pour pouvoir être partagé sans risque.

Confirmez que le moteur relit vos modifications sans erreur :

apothem profile show --json

Si le YAML est malformé, c'est ici que vous le verrez — corrigez-le et relancez la commande avant de poursuivre.

Étape 3 — Matérialiser une configuration d'environnementCopy Anchor Link

Si votre exécution de l'Étape 1 a créé le profil, elle a déjà installé Claude Code à partir de l'identité provisoire. Modifiez le profil à l'Étape 2, puis appliquez votre identité avec :

apothem update --harness claude-code

apothem install --harness claude-code

Cette commande lit votre profil et écrit la configuration native de Claude Code. Pour voir tous les environnements que vous pouvez cibler :

apothem harnesses list

Certains environnements sont à portée projet plutôt qu'à portée utilisateur, et ceux-là ont besoin d'un chemin --project pour que l'adaptateur sache où écrire :

apothem install --harness cursor --project .

Étape 4 — Vérifier et confirmer une première exécutionCopy Anchor Link

Matérialiser n'est que la moitié de l'histoire. Confirmez maintenant que la configuration est bien en place :

apothem verify --harness claude-code

verify contrôle que les fichiers de configuration gérés de l'environnement existent et s'analysent correctement. Ajoutez --profile PATH et il échoue aussi lorsqu'un fichier installé a dérivé de ce que ce profil produirait. Une exécution propre signifie que la matérialisation a réussi.

Pour un contrôle de santé de toute la machine sur chaque adaptateur enregistré, exécutez :

apothem doctor

doctor vérifie chaque environnement installé (celui-ci doit passer la vérification, et ses commandes de hook enregistrées doivent démarrer) et se termine avec un code non nul si un contrôle échoue. Les environnements que vous n'avez pas installés sont listés mais ne le font pas échouer ; c'est donc un portail utile dans un script de configuration.

Votre première exécution. Ouvrez l'environnement que vous venez de configurer — Claude Code, dans notre exemple — et démarrez une session dans n'importe quel projet. Les règles et préférences que vous avez écrites dans le profil font désormais partie du comportement de cet outil. C'est la première exécution fonctionnelle : le profil que vous avez édité à l'Étape 2 façonne une session réelle.

Ce que vous avez construitCopy Anchor Link

En partant d'une machine vierge, vous avez installé Apothem, rédigé un profil partagé, matérialisé à partir de celui-ci la configuration native d'un environnement, vérifié le résultat et confirmé son fonctionnement. Le profil est l'artefact durable : modifiez-le une fois et relancez apothem update --harness <name> pour propager la modification à n'importe quel environnement.

Où aller ensuiteCopy Anchor Link

• Ajoutez un autre outil. La liste des environnements couvre chaque plateforme prise en charge et son nom d'adaptateur. Répétez l'Étape 3 avec un nouveau --harness.
• Approfondissez une tâche précise. Les recettes pratiques couvrent l'ajout d'un environnement, l'édition du profil et le pilotage de l'installateur. Les guides d'utilisation couvrent l'écriture de règles, la rédaction de plans et l'exécution du portail de conformité.
• Consultez les détails. La référence documente chaque classe d'artefacts et le schéma du profil, et la référence de la CLI couvre chaque commande. Chaque adaptateur a sa propre page sous environnements.
• Planifiez un travail qui survit à une session. La planification reprenable explique comment Apothem externalise le travail de longue durée dans une suite .apothem/plans/ locale au projet, de sorte qu'une nouvelle session sur n'importe quelle machine le reprenne là où il en était.

Prochaine étape recommandéeCopy Anchor Link

Exécutez apothem doctor pour contrôler votre configuration — il signale l'état de chaque adaptateur enregistré, de sorte que l'environnement que vous venez d'installer apparaît comme sain tandis que les autres apparaissent comme pas encore installés — avant de passer à l'ajout d'autres environnements.