# La CLI capibara > Installer la commande capibara, lier un dossier au projet du portail par une clé de projet, développer en deploy-on-save sur votre organisation de test, lire le journal, créer et publier une version — sans tunnel ni émulateur. > Catégorie : Démarrer · mis à jour le 2026-09-04 · plateforme v1 ## Ce que fait la CLI Une app Capibara se développe **comme un bot Discord** : votre code tourne chez Capibara, la CLI l'y envoie. Pas de tunnel, pas d'émulateur, pas de serveur local à exposer — `capibara dev` bundle vos sources sur la plateforme, les pose sur **votre organisation de test** dans la vraie sandbox (un isolate dédié à votre version de test) et vous rend le journal en direct. Chaque sauvegarde redéploie en quelques secondes. ```bash capibara init --template page --app ma-premiere-app # un projet complet capibara login --key cpk_… # la clé de projet capibara dev --org mon-organisation # deploy-on-save + journal capibara deploy # version → review capibara deploy --publish # publication, une fois approuvée ``` --- ## Installation ```bash npm install -D @capibara-dev/cli @capibara-dev/sdk # registre npm public npx capibara --help ``` Zéro dépendance, Node ≥ 18. Sans accès au registre npm, le tarball servi par le portail fait la même chose : ```bash curl -O https://capibara.fr/dev-cli/capibara-dev-cli-0.1.2.tgz npm install -D ./capibara-dev-cli-0.1.2.tgz ``` Les starters installent aussi le [SDK](/dev/docs/sdk) (types + harnais de test). --- ## 1. Le projet et sa clé 1. Créez le projet dans le portail (`/dev`) : son identifiant `key` est immuable, c'est celui que vous donnerez à `capibara init --app`. 2. Sur la page de l'app, section **Code**, carte « Clé de projet & CLI » : **Générer une clé**. La clé `cpk_…` n'est affichée **qu'une fois** ; copiez-la dans `capibara login`. Une clé de projet est **bornée au projet** : ce n'est ni une clé de compte, ni un accès aux données d'une organisation. Elle est stockée hachée, révocable à tout moment (jusqu'à 10 clés par projet), et chaque usage est journalisé (dernier usage, compteur). Les installations de test qu'elle pose ne peuvent viser qu'une organisation dont **vous** (le créateur de la clé) êtes propriétaire. --- ## 2. `capibara init` — un projet complet depuis un starter ```bash capibara init --template page --app ma-premiere-app [--name "Ma première app"] [--dev ] [--dir mon-app] ``` | Starter | Contenu | |---|---| | `page` (défaut) | Une page d'app (entrée de menu `view`) + un widget d'accueil, un compteur en KV, deux actions. | | `panel` | Un panneau sur les fiches contact/société du CRM (lecture par façade, scope feuille minimal). | | `cron` | Une planification (`schedules`) + un widget qui affiche la dernière exécution. | | `external` | Une app hybride : page embarquée (`embedUrl`) + `server/webhook.ts` avec `createServerHandler` (backend chez vous). | | `blank` | Le squelette minimal (`defineApp` vide + manifeste). | Chaque starter crée `add-on.json`, `capibara.json`, `src/index.ts`, un `package.json` (SDK + CLI en devDependencies, `npm test` avec le harnais), `tsconfig.json`, `.gitignore` et un README. Si vous n'indiquez pas `--dev`, `author.devAccountSlug` est complété par `capibara login`. --- ## 3. `capibara login` — lier le dossier au projet ```bash capibara login --key cpk_… [--url https://…] ``` La CLI vérifie la clé auprès de la plateforme, l'enregistre dans `.capibara/key` (mode 600, ajouté au `.gitignore`), aligne `capibara.json` (`app`, `baseUrl` si vous visez une autre instance) et complète `author.devAccountSlug` dans le manifeste. En CI ou dans un conteneur, exportez plutôt `CAPIBARA_PROJECT_KEY`. --- ## 4. `capibara dev` — développer en deploy-on-save ```bash capibara dev --org mon-organisation # --once : un seul déploiement ; --no-logs : sans le journal ``` À chaque sauvegarde : 1. la CLI envoie le manifeste et vos sources (`.ts`, `.tsx`, `.js`, `.mjs`, `.json` — hors `node_modules`, `dist`, `tests`, `server`, fichiers de test et d'outillage ; 80 fichiers, 1,5 Mo au total, 512 Ko par fichier) ; 2. la plateforme **valide le manifeste** (mêmes règles que le portail — la clé et `author.devAccountSlug` doivent être les vôtres), **scanne les sources** (secrets, motifs interdits : refus avant toute construction), **bundle** avec son propre bundler (imports relatifs + `@capibara-dev/sdk` uniquement) et enregistre le bundle sur la version **brouillon** du manifeste (créée si besoin) ; 3. elle pose (ou met à jour) l'**installation de test** sur l'organisation choisie — même consentement, même compte de service qu'une installation réelle, bandeau « version de test », jamais comptée ni listée ; 4. l'isolate de test (`@`, servi à côté de l'app publiée) recharge le nouveau bundle en une dizaine de secondes — **la CLI attend qu'il soit monté avec ce bundle** (jusqu'à 60 s) et l'écrit : `OK Isolate meteo@cmt… monté et à jour (12 s)`. Puis la CLI affiche le **journal** en direct : chaque interaction (page, action, événement, planification, HTTP) avec son statut, sa latence, l'erreur éventuelle et vos `ctx.log`. Les erreurs de validation du Kit renvoyées par la plateforme y apparaissent en clair. ### Si l'isolate ne se monte pas Trois étapes séparent votre déploiement de son exécution : le worker de la plateforme écrit la configuration du runtime, le conteneur du runtime la télécharge et se recharge, le routeur sert votre route. Quand l'une bloque, la CLI (et `capibara status`) nomme l'étape avec le remède, et le journal dit la même chose au lieu d'un « HTTP 404 » muet : | Message | Ce que ça veut dire | |---|---| | *configuration pas régénérée* | Le job `addon-runtime-config` du worker n'a pas encore tourné (il est relancé à chaque déploiement, à chaque exécution en échec et toutes les 5 minutes). S'il ne tourne jamais, le worker de l'instance n'est pas démarré ou pas à jour. | | *pas chargé par le conteneur* | La configuration contient votre route mais le conteneur `addon-runtime` ne l'a pas rechargée (bundle introuvable, SHA-256 refusé, API interne injoignable). | | *bundle antérieur* | L'isolate tourne encore sur le bundle précédent : rechargement en cours (~10–20 s). | | *runtime injoignable* | Le conteneur redémarre (normal pendant un rechargement) ou n'est pas démarré. | Rien de tout cela ne vient de votre code : un exécutant de l'instance (`docker compose logs worker addon-runtime`) règle le point. Vos erreurs à vous — Kit invalide, exception dans un handler — restent dans le journal, sous leur vrai nom. Une version en `REVIEW`, `APPROVED` ou `PUBLISHED` n'est jamais réécrite : la CLI répond `version_locked` — incrémentez `version` dans le manifeste et relancez. Une version `REJECTED` est reprise comme un brouillon. --- ## 5. `capibara deploy` — créer et publier une version ```bash capibara deploy # bundle + version du manifeste → REVIEW (build automatisé + review humaine) capibara deploy --version 1.2.0 # impose le semver capibara deploy --publish # publie une version APPROVED (ou la dernière approuvée) capibara publish # alias de deploy --publish ``` Le cycle reste celui de [Publication et review](/dev/docs/publication) : rien ne se publie sans approbation, et la publication reste un geste explicite. `capibara status` montre l'état de chaque version. --- ## Les autres commandes | Commande | Ce qu'elle fait | |---|---| | `capibara status [--json]` | Projet, clé utilisée, versions (canal, bundle), installations de test **avec l'état de leur isolate** (monté / bundle antérieur / pas chargé / configuration pas régénérée, et le remède), organisations cibles. | | `capibara logs [--org ] [--follow] [--limit N]` | Journal des exécutions sur vos installations de test (`--follow` = flux continu). | | `capibara install [--org ] [--version x.y.z]` | Pose une installation de test sans redéployer ; `--remove` la retire (et purge ses données). | | `capibara scopes` | Les scopes du manifeste avec leur phrase de consentement, et ce que chaque organisation de test a accordé (« manque : … » = re-consentement nécessaire). | | `capibara kit check [--surface page]` | Valide un document (ou un nœud) du Kit avec le **vrai** validateur de la plateforme : erreurs nommées, statistiques. | Options communes : `--url ` (ou `CAPIBARA_URL`), `--debug`, `--no-color`. Codes de sortie : `0` succès, `1` erreur (message + indice), `2` usage incorrect ou document du Kit invalide. --- ## Fichiers et variables | Fichier / variable | Rôle | |---|---| | `capibara.json` (committé) | `{ "app": "", "manifest": "add-on.json", "baseUrl"?: "https://…", "org"?: "" }` — `org` évite de répéter `--org`. | | `.capibara/key` (hors git) | La clé de projet, écrite par `capibara login`. | | `CAPIBARA_PROJECT_KEY` | Alternative à `.capibara/key` (CI, conteneurs). | | `CAPIBARA_URL` / `--url` | Origine de la plateforme (défaut `https://capibara.fr`). | --- ## Limites et sécurité - Le bundle est **toujours** construit par la plateforme : pas de `node_modules`, imports relatifs + `@capibara-dev/sdk` seulement. Les dossiers `tests/` et `server/` restent chez vous. - Corps d'une requête ≤ 3 Mo ; 240 appels par minute et 60 déploiements par minute par clé de projet. - Une installation de test exécute votre code hébergé (`main`) ou appelle votre [backend externe](/dev/docs/backend-externe) (`backend.url`) ; une app hybride (ni l'un ni l'autre) se teste avec son backend chez vous — `capibara status` la marque « hybride ». - Ne committez jamais `.capibara/key`. Une clé compromise se révoque depuis le portail (section Code) — les installations de test restent. --- ## Sans la CLI Tout ce que fait la CLI passe par l'[API de projet](/dev/docs/api-publique) (`/api/public/v1/project/…`, `Authorization: Bearer cpk_…`) : `curl` ou n'importe quel client HTTP fonctionne. Le portail sait aussi tout faire **sans rien installer** : l'**Édition rapide** de la section Code est un éditeur (Monaco, avec les types du SDK `@capibara-dev/sdk` chargés — complétion et erreurs en direct) sur les fichiers de la version en cours. « Enregistrer » crée ou met à jour le brouillon exactement comme `capibara deploy` sans `--publish` ; « Déployer » choisit l'une de vos organisations de test et suit le **même chemin que `capibara dev`** (validation, scan, bundle, installation de test, isolate rechargé). La section Tests montre l'état de l'isolate et le journal en direct ; la section Journal, l'usage par installation. Un projet créé depuis un starter de l'assistant a déjà ses fichiers dans l'Édition rapide ; un projet déployé par la CLI les y retrouve aussi (les sources accompagnent chaque version). Le dépôt Git connecté, l'installation de test depuis la fiche et le Kit Studio restent disponibles.