Capibara
Documentation

Démarrer

La CLI capibara

Mis à jour le 4 septembre 2026Plateforme v1 Markdown brut

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.

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

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 :

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 (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

capibara init --template page --app ma-premiere-app [--name "Ma première app"] [--dev <votre-slug>] [--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

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

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 (<clé>@<version>, 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

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 :
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 <slug>] [--follow] [--limit N] Journal des exécutions sur vos installations de test (--follow = flux continu).
capibara install [--org <slug>] [--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 <fichier.json> [--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 <origine> (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": "<clé>", "manifest": "add-on.json", "baseUrl"?: "https://…", "org"?: "<slug>" } — 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 (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
(/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.

La CLI capibara · Capibara for Developers