référence

Le CLI forge, commande par commande

Dans l'ordre de découverte, avec un aide-mémoire en tête et une table des matières pour aller droit au but.

Les commandes sont présentées dans l'ordre où on les rencontre : installer, se connecter, écrire, éprouver, publier, exploiter. La table des matières à gauche permet d'aller directement à une commande précise.

Aide-mémoire#

Commande	Effet
`forge init`	Initialisation guidée : workspace, connexion, récupération des agents, skill
`forge signup <email> --team <nom>`	Crée votre équipe puis vous connecte
`forge login [email]` / `whoami` / `logout`	Session par lien magique, identité, déconnexion
`forge pull [slug]`	Déploiement → fichiers
`forge push <slug> [--activate]`	Fichiers → déploiement (miroir) ; `--activate` publie
`forge diff <slug>`	Ce qui diverge entre local et déployé
`forge run <slug> --payload '<json>'`	Exécute l'agent
`forge tool <slug> <nom> [--args '<json>']`	Exécute un seul outil, sans LLM
`forge bench <slug> [--case <nom>]`	Rejoue le golden set
`forge verdict <slug> --case <nom> --run <id> --passed\|--failed`	Enregistre un jugement
`forge runs <slug>` / `trace <runId>` / `verdicts <slug>`	Historique, trace détaillée, qualité
`forge versions <slug>` / `pull <slug> --version <n>`	Timeline et rollback
`forge secret set <slug> NAME=VALUE`	Secret sur le worker de l'agent
`forge keys create\|list\|revoke`	Clés API du tenant
`forge status` / `llm set\|clear` / `credit add\|history`	Crédit, clés BYOK, recharge
`forge invite <email>`	Invite un collègue dans l'équipe
`forge ui [--port N]`	UI d'administration locale
`forge update` / `kit update`	Met à jour le binaire, puis `lib/`

Installer#

macOS et Linux, binaire unique sans dépendance :

curl -fsSL https://agent-forge.cc/download/forge-darwin-arm64 -o forge
chmod +x forge && sudo mv forge /usr/local/bin/

Sur macOS, un installeur .dmg est également disponible depuis la page de téléchargement. forge update met ensuite le binaire à jour depuis la dernière version publiée ; forge kit update réécrit la bibliothèque lib/ du workspace en conséquence.

Piloter Forge depuis un agent de code#

C'est le mode d'emploi nominal. forge init — ou forge skill install seul — dépose dans votre workspace :

.claude/skills/forge/ et .claude/skills/agent-dev/ pour Claude Code ;
AGENTS.md à la racine pour Codex, qui le lit nativement ;
un CLAUDE.md d'ancrage si le workspace n'en a pas.

Ces fichiers décrivent à votre assistant l'ensemble des commandes, la méthodologie d'itération, les pièges connus et les principes de prompting propres à chaque famille de modèle. Concrètement, vous écrivez « ajoute un cas golden sur les requêtes ambiguës et fais passer le bench » : l'assistant crée le fichier, pousse, lance le bench, lit les traces et corrige.

Tout est réinstallable à volonté — forge skill install est idempotent et réécrit la skill après chaque mise à jour du binaire.

Créer son équipe#

forge signup vous@exemple.com --team votre-equipe

Crée le tenant, puis enchaîne sur la connexion. Sans invitation préalable, l'équipe démarre en offre gratuite : crédit LLM de découverte et quota de recherche web mensuel.

La connexion se fait par lien magique. Un code de vérification s'affiche dans le terminal et doit correspondre à celui de la page ouverte depuis l'email — c'est ce qui protège d'un lien intercepté ou collé ailleurs. La session dure 90 jours.

forge whoami affiche l'identité et le tenant courants, forge logout révoque la session et efface les identifiants locaux.

Le workspace#

forge init

Réexécutable sans risque : la commande reprend où elle s'est arrêtée. Elle résout le workspace, connecte si besoin, récupère tous les agents de l'équipe, installe la skill, dépose la bibliothèque lib/ et un agent d'exemple.

Le workspace est le dossier contenant agents/. Il est résolu dans cet ordre : la variable FORGE_WORKSPACE, puis un dossier agents/ déjà présent dans le répertoire courant, puis ~/forge.

forge init propose aussi d'initialiser un dépôt git s'il n'y en a pas — vivement recommandé : Forge versionne ce qu'il exécute, mais l'historique de vos sources reste le travail de git.

Écrire un agent#

forge push#

forge push mon-agent
forge push mon-agent --activate

Envoie les fichiers vers le déploiement. La sémantique est un miroir : un cas golden supprimé localement est supprimé côté serveur. Les fichiers font toujours foi dans leur intégralité.

Si agent.json porte runtime: "worker", le CLI bundle agent.ts et le déploiement Cloudflare est relayé par le control plane — le CLI ne détient jamais de jeton Cloudflare.

--activate publie l'agent. La règle de méthode : jamais d'activation sans golden set vert.

forge pull, forge diff#

forge pull récupère les agents de l'équipe vers les fichiers ; forge pull <slug> un seul. forge diff <slug> liste les champs qui divergent et sort en code 1 s'il y a une différence — utilisable dans un script de vérification.

Exécuter#

forge run mon-agent --payload '{"query":"..."}'

L'exécution est distante par défaut : elle consomme un run réel, avec son coût LLM, et elle est tracée. --local est réservé au développement dans le dépôt source, avec les clés en local.

forge tool#

forge tool mon-agent --list
forge tool mon-agent musicme_search --args '{"q":"..."}'

Exécute un seul outil, sans appeler le modèle : zéro token dépensé. Les secrets restent côté worker, votre session suffit. C'est la façon la plus économique d'explorer une API depuis le terminal et de comprendre ce que l'agent voit réellement.

Éprouver#

forge bench#

forge bench mon-agent
forge bench mon-agent --case requete-ambigue

Rejoue le golden set. Chaque cas coûte un run réel — pendant une correction, ciblez un seul cas avec --case plutôt que de tout rejouer.

forge trace, runs, verdicts#

forge runs <slug> liste les derniers runs avec statut, tokens, coût, latence et version. forge trace <runId> déplie la trace complète : étapes LLM, appels d'outils, entrées et sorties, erreurs.

Deux variantes précieuses en analyse d'incident : --version restitue l'état complet de l'agent qui a produit ce run, --prompt en extrait les seuls prompts.

forge verdict <slug> --case <nom> --run <runId> --passed|--failed [--notes '…'] enregistre le jugement, et forge verdicts <slug> donne l'historique par cas.

Versionner#

forge versions mon-agent
forge pull mon-agent --version 7

La timeline indique, pour chaque version, ce qui a changé : prompt, code, lib, config ou statut. Le pull --version réécrit les fichiers du workspace depuis une version antérieure — c'est le rollback, à repousser ensuite comme une modification normale.

Publier et consommer#

Une fois l'agent activé, il s'invoque par HTTPS :

curl -N https://agents.agent-forge.cc/mon-agent/invoke \
  -H "x-api-key: fak_…" \
  -H "content-type: application/json" \
  -d '{"query":"..."}'

La réponse est un flux SSE terminé par {"type":"final","output":…}.

forge keys#

forge keys create production
forge keys list
forge keys revoke <id>

La clé n'est affichée qu'une fois. Elle donne accès à tous les agents de l'équipe : réservez-la à vos serveurs, jamais à du code navigateur.

Secrets et environnement#

forge secret set mon-agent MON_API_KEY=…

Pose ou fait tourner un secret sur le worker déployé. C'est le seul moyen correct d'injecter une clé pour un outil maison — jamais en dur dans le code, jamais dans un fichier de configuration versionné.

forge env pull écrit les variables du déploiement dans .env.forge (ignoré par git), pour le développement local dans le dépôt source.

Facturation et clés LLM#

forge status
forge llm set gateway sk-…
forge credit add 20
forge credit history

forge status affiche le crédit, les clés BYOK de l'équipe et le quota de recherche web du mois. forge llm set gateway|openrouter pose la clé de l'équipe : dès lors les runs passent par votre fournisseur et le crédit n'est plus consommé. forge llm clear revient aux clés de la plateforme.

forge credit add <montant> ouvre une page de paiement sécurisée (minimum 10 $). Le crédit est appliqué dès validation du paiement, indépendamment de l'onglet du navigateur ; forge status fait foi.

Équipe#

forge invite <email> invite un collègue dans l'équipe courante — réservé aux administrateurs. Pensez à indiquer dans votre message la page de téléchargement : votre invité n'a pas encore de quoi se connecter.

Administration locale#

forge ui
forge ui --port 5180 --open

Lance l'interface d'administration, embarquée dans le binaire, sur http://localhost:36743 par défaut : agents, runs et traces détaillées, versions, verdicts, paramètres de facturation. forge app est le mode double-clic (installe le CLI puis ouvre l'interface).

Codes de sortie#

Toutes les commandes renvoient 0 en succès et 1 en erreur, le message étant préfixé de ✗. forge diff est le cas particulier utile en script : 1 signifie « différent », pas « échec ».