Référence CLI

La CLI OpenSpec (openspec) fournit des commandes de terminal pour la configuration de projet, la validation, l'inspection d'état et la gestion. Ces commandes complètent les commandes slash IA (comme /opsx:propose) documentées dans Commandes.

Résumé

Catégorie	Commandes	Objectif
Configuration	init, update	Initialiser et mettre à jour OpenSpec dans votre projet
Stores (dépôts OpenSpec autonomes)	store setup, store register, store unregister, store remove, store list, store doctor	Gérer les stores — dépôts OpenSpec autonomes que vous avez enregistrés
Santé	doctor	Rapporter l'état de santé des relations pour la racine résolue
Contexte de travail	context	Assembler l'ensemble de travail (racine + stores référencés)
Worksets personnels	workset create, workset list, workset open, workset remove	Conserver et ouvrir des vues de travail personnelles et locales dans votre outil
Navigation	list, view, show	Explorer les changements et les spécifications
Validation	validate	Vérifier les changements et spécifications pour détecter des problèmes
Cycle de vie	archive	Finaliser les changements terminés
Flux de travail	new change, status, instructions, templates, schemas	Support de flux de travail piloté par les artefacts
Schémas	schema init, schema fork, schema validate, schema which	Créer et gérer des flux de travail personnalisés
Configuration	config	Afficher et modifier les paramètres
Utilitaires	feedback, completion	Retour d'information et intégration au shell

---

Commandes humaines vs agent

La plupart des commandes CLI sont conçues pour une utilisation humaine dans un terminal. Certaines commandes prennent également en charge une utilisation par agent/script via la sortie JSON.

Commandes réservées aux humains

Ces commandes sont interactives et conçues pour une utilisation en terminal :

Commande	Objectif
openspec init	Initialiser le projet (invites interactives)
openspec view	Tableau de bord interactif
openspec workset open <name>	Ouvrir un workset sauvegardé (fenêtre d'éditeur ou session agent en terminal)
openspec config edit	Ouvrir la configuration dans l'éditeur
openspec feedback	Soumettre des commentaires via GitHub
openspec completion install	Installer les complétions de shell

Commandes compatibles avec les agents

Ces commandes prennent en charge la sortie --json pour une utilisation programmatique par des agents IA et des scripts :

Commande	Utilisation humaine	Utilisation agent
openspec list	Parcourir les modifications/spécifications	--json pour des données structurées
openspec show <item>	Lire le contenu	--json pour l'analyse
openspec validate	Vérifier les problèmes	--all --json pour une validation en masse
openspec status	Voir la progression des artefacts	--json pour un statut structuré
openspec instructions	Obtenir les prochaines étapes	--json pour les instructions d'agent
openspec templates	Trouver les chemins des modèles	--json pour la résolution de chemins
openspec schemas	Lister les schémas disponibles	--json pour la découverte de schémas ; --store <id> pour sélectionner une racine enregistrée
openspec store setup <id>	Créer et enregistrer un store local	--json avec des entrées explicites pour une sortie de configuration structurée
openspec store register <path>	Enregistrer un store existant	--json pour une sortie d'enregistrement structurée
openspec store unregister <id>	Oublier un enregistrement de store local	--json pour une sortie de nettoyage structurée
openspec store remove <id>	Supprimer un dossier de store local enregistré	--yes --json pour une suppression non interactive
openspec store list	Parcourir les stores enregistrés	--json pour des enregistrements structurés
openspec store doctor	Vérifier la configuration du store local	--json pour des diagnostics structurés
openspec new change <id>	Créer un échafaudage de changement local au dépôt	--json, plus --store <id> pour utiliser un store enregistré comme racine OpenSpec
openspec workset create [name]	Composer une vue de travail personnelle	--member <path> --json pour une composition non interactive
openspec workset list	Parcourir les worksets sauvegardés	--json pour des vues structurées
openspec workset remove <name>	Supprimer une vue sauvegardée	--yes --json pour une suppression non interactive

---

Options globales

Ces options fonctionnent avec toutes les commandes :

Option	Description
--version, -V	Afficher le numéro de version
--no-color	Désactiver la sortie couleur
--help, -h	Afficher l'aide pour la commande

---

Commandes de configuration

openspec init

Initialise OpenSpec dans votre projet. Crée la structure de dossiers et configure les intégrations d'outils IA.

Le comportement par défaut utilise les valeurs par défaut de la configuration globale : profil core, livraison both, workflows propose, explore, apply, update, sync, archive.

openspec init [path] [options]

Utilisez --language <language> pour ajouter une instruction de langue au fichier openspec/config.yaml d'un nouveau projet. Pour un projet existant, modifiez le champ context de la configuration afin qu'OpenSpec ne remplace jamais les directives spécifiques au projet.

Arguments :

Argument	Requis	Description
path	Non	Répertoire cible (par défaut : répertoire courant)

Options :

Option	Description
--tools <list>	Configure les outils IA de manière non interactive. Utilisez all, none ou une liste séparée par des virgules
--language <language>	Rédiger les artefacts dans cette langue lors de la création d'une nouvelle configuration
--force	Nettoyage automatique des fichiers hérités sans invitation
--profile <profile>	Remplacer le profil global pour cette exécution d'init (core ou custom)
--no-animation	Afficher un écran d'accueil statique au lieu de l'écran animé
--copilot-cloud	Configurer les fichiers cloud coding-agent de GitHub Copilot sans invitation
--no-copilot-cloud	Ignorer les fichiers cloud coding-agent de GitHub Copilot sans invitation

--profile custom utilise les workflows actuellement sélectionnés dans la configuration globale (openspec config profile).

L'animation de bienvenue est également ignorée lorsque la variable d'environnement OPENSPEC_NO_ANIMATION est définie (toute valeur, y compris vide), lorsque NO_COLOR est défini à une valeur non vide, ou lorsque la préférence de mouvement réduit du système est activée (Réduire le mouvement sur macOS, animations GNOME désactivées).

Identifiants d'outils pris en charge (--tools) — windsurf est également accepté, comme alias pour devin : amazon-q, antigravity, auggie, bob, claude, cline, command-code, codeartsagent, codex, devin, forgecode, codebuddy, continue, costrict, crush, cursor, factory, gemini, github-copilot, hermes, iflow, junie, kilocode, kimi, kiro, lingma, minimax-code, vibe, oh-my-pi, opencode, pi, codeassistant, qoder, qwen, rovodev, roocode, trae, zed, zcode, agents

Cette liste reflète AI_TOOLS dans src/core/config.ts. Voir Outils pris en charge pour les compétences et chemins de commande de chaque outil.

Exemples :

# Initialisation interactive
openspec init

# Initialisation dans un répertoire spécifique
openspec init ./my-project

# Non interactif : configurer pour Claude et Cursor
openspec init --tools claude,cursor

# Non interactif : configurer les compétences globales MiniMax Code
openspec init --tools minimax-code

# Configurer pour tous les outils pris en charge
openspec init --tools all

# Remplacer le profil pour cette exécution
openspec init --profile core

# Ignorer les invites et nettoyer automatiquement les fichiers hérités
openspec init --force

Ce qu'il crée :

openspec/
├── specs/              # Vos spécifications (source de vérité)
├── changes/            # Modifications proposées
└── config.yaml         # Configuration du projet

.claude/skills/         # Compétences Claude Code (si claude est sélectionné)
.cursor/skills/         # Compétences Cursor (si cursor est sélectionné)
.cursor/commands/       # Commandes Cursor OPSX (si la livraison inclut les commandes)
.agents/skills/         # Compétences partagées pour les outils compatibles AGENTS.md (si agents est sélectionné)
... (autres configurations d'outils)

---

openspec update

Met à jour les fichiers d'instructions OpenSpec après la mise à niveau du CLI. Régénère les fichiers de configuration des outils IA en utilisant votre profil global actuel, les workflows sélectionnés et le mode de livraison.

openspec update [path] [options]

Arguments :

Argument	Requis	Description
path	Non	Répertoire cible (par défaut : répertoire courant)

Options :

Option	Description
--force	Forcer la mise à jour même si les fichiers sont à jour

Exemple :

# Mettre à jour les fichiers d'instructions après la mise à niveau npm
npm install -g @fission-ai/openspec@latest
openspec update

Mettez à niveau le paquet d'abord. Les fichiers d'instructions sont générés par le CLI installé, donc exécuter openspec update avec une installation obsolète rapporte que tout est à jour sans ajouter les workflows fournis par les versions plus récentes.

Pour rendre cela visible, openspec update interroge le registre npm pour savoir si un CLI plus récent a été publié. Lorsque le vôtre est en retard, il propose de le mettre à niveau :

A newer OpenSpec CLI is available (v1.6.0 → v1.7.0).
  Running from: /usr/local/lib/node_modules/@fission-ai/openspec
? Upgrade to v1.7.0 now? (Y/n)

Répondez oui et il exécute npm install -g @fission-ai/openspec@latest, puis relance la mise à jour avec le nouveau CLI afin que les nouveaux workflows arrivent dans la même commande. Il confirme la mise à niveau en demandant au binaire installé sa version plutôt qu'en se fiant au code de sortie de npm, donc si une autre installation précédente sur votre PATH répond encore, il vous le dit au lieu de prétendre avoir réussi. Répondez non et il affiche la commande et met à jour avec le CLI que vous avez. Ctrl-C arrête la commande.

L'offre n'apparaît que dans un terminal interactif, et uniquement lorsque npm possède l'installation — le seul cas où npm install -g corrige réellement. Tout le reste obtient la commande qui correspond à la façon dont il a été installé :

Comment OpenSpec est installé	Ce que vous obtenez
Installation npm globale	La prompte, et la mise à niveau exécutée pour vous — dans un terminal interactif ; la sortie redirigée obtient la commande imprimée à la place
Installation globale pnpm, bun, yarn ou volta	La commande propre à ce gestionnaire : pnpm add -g …@latest, bun add -g …@latest, yarn global add …@latest, ou volta install …@latest
Une dépendance du projet	Une note pour mettre à jour la dépendance, car son gestionnaire de paquets possède le lockfile
Un cache npx / dlx	npx @fission-ai/openspec@latest update — cette commande est la mise à jour, donc il n'y a pas de deuxième étape
Un clone git	Rien — votre version est celle que dit la branche

Chaque fois que quelque chose est imprimé, il nomme le répertoire d'où le CLI en cours a été chargé — l'élément à vérifier lorsque vous avez effectué une mise à niveau mais qu'un ancien shim possède encore votre PATH.

Il interroge le registre dans npm_config_registry lorsque npm l'exporte, et https://registry.npmjs.org sinon. Aucun .npmrc n'est lu : laisser le contenu d'un fichier choisir où une requête sortante va est un flux à éviter, et un .npmrc de projet voyage avec le dépôt. Sur un miroir privé, exportez npm_config_registry — ou définissez OPENSPEC_NO_UPDATE_CHECK pour ignorer complètement la vérification. La vérification est ignorée lorsque CI est défini à autre chose qu'une valeur d'arrêt explicite (false, 0, no, off ou vide), sous NODE_ENV=test, et chaque fois que OPENSPEC_NO_UPDATE_CHECK (toute valeur), DO_NOT_TRACK=1 ou OPENSPEC_TELEMETRY=0 est défini. Elle s'exécute avant la mise à jour et peut la retarder d'au plus 1,5 seconde — elle abandonne après cela même si le réseau perd silencieusement des paquets, et reste silencieuse lorsque le registre est inaccessible.

Comment « à jour » est décidé : les fichiers de compétences enregistrent la version qui les a générés, donc OpenSpec la compare au CLI installé. Les fichiers de commandes ne portent aucun tampon de version, donc pour un outil qui a des commandes mais pas de compétences (livraison commands), OpenSpec compare le contenu des fichiers avec ce qu'il générerait maintenant — les modifications de ces fichiers comptent comme dérive et sont écrasées. Avec la livraison skills ou both, seule la version enregistrée est vérifiée, donc un fichier modifié manuellement dont la version correspond toujours est laissé tranquille ; utilisez --force pour le réécrire. Dans les deux cas, les fichiers générés appartiennent à OpenSpec — gardez vos propres instructions ailleurs.

---

Magasins (dépôts OpenSpec autonomes)

Bêta. Les magasins et les fonctionnalités construites dessus (références, contexte de travail, ensembles de travail) sont nouveaux ; les noms de commandes, les indicateurs, les formats de fichiers et la sortie JSON peuvent changer entre les versions. Pour un guide pas à pas axé sur le problème, consultez le guide des magasins.

Un magasin est un dépôt OpenSpec autonome que vous avez enregistré sur cette machine — par exemple, un dépôt de planification ou un dépôt de contrats. L'enregistrement d'un magasin permet aux commandes normales (list, show, status, validate, new change, archive, ...) de s'y exécuter depuis n'importe où en passant --store <id>.

openspec store setup

Crée et enregistre un magasin local. Sans arguments dans un terminal, OpenSpec guide l'utilisateur à travers la configuration. Les agents et les scripts doivent passer des entrées explicites et utiliser --json.

openspec store setup [id] [options]

Options :

Option	Description
--path <path>	Dossier où le magasin doit être situé (par exemple ~/openspec/<id>)
--remote <url>	Enregistrer le distant canonical dans le store.yaml du nouveau magasin
--init-git	Initialiser un dépôt Git avec un commit initial (par défaut)
--no-init-git	Ignorer toutes les actions Git : pas d'initialisation, pas de commit initial
--json	Sortie JSON

Les exécutions non interactives (--json, scripts, agents) doivent passer à la fois l'identifiant du magasin et --path. Dans un terminal interactif, la configuration demande l'emplacement avec une suggestion éditable dans un endroit visible et appartenant à l'utilisateur (par exemple ~/openspec/<id>) ; elle ne choisit jamais par défaut le répertoire de données géré par OpenSpec.

Exemples :

openspec store setup
openspec store setup team-context
openspec store setup team-context --path ~/openspec/team-context --no-init-git
openspec store setup team-context --path ~/openspec/team-context --no-init-git --json

openspec store register

Enregistre un dossier de magasin local existant. Pendant la phase bêta des magasins, une racine peut être enregistrée avant qu'il n'y ait des changements, que les spécifications aient été appliquées ou que les changements aient été archivés ; dans ce cas, openspec/changes/, openspec/specs/ et openspec/changes/archive/ peuvent être absents jusqu'à ce que les commandes normales les créent. Un dépôt contenant uniquement une configuration qui déclare store: <id> reste un pointeur vers un autre magasin et n'est pas enregistré comme racine de magasin à moins que ce pointeur ne soit supprimé.

openspec store register [path] [options]

Options :

Option	Description
--id <id>	Identifiant du magasin ; par défaut, utilise les métadonnées du magasin ou le nom du dossier
--yes	Confirmer la création des métadonnées d'identité du magasin pour une racine OpenSpec valide
--json	Sortie JSON

openspec store unregister

Oublie l'enregistrement d'un magasin local sans supprimer les fichiers.

openspec store unregister <id> [--json]

Utilisez ceci lorsqu'un magasin a été déplacé, cloné ailleurs, ou ne devrait plus être affiché par OpenSpec sur cette machine.

openspec store remove

Oublie l'enregistrement d'un magasin local et supprime son dossier local.

openspec store remove <id> [--yes] [--json]

remove affiche le dossier exact avant de le supprimer dans un terminal interactif. Les agents, les scripts et les appelants JSON doivent passer --yes pour confirmer la suppression. OpenSpec refuse de supprimer un dossier qui ne contient pas de métadonnées de magasin correspondantes.

openspec store list

Liste les magasins enregistrés localement.

openspec store list [--json]
openspec store ls [--json]

openspec store doctor

Vérifie l'enregistrement local du magasin, les métadonnées et la présence de Git.

openspec store doctor [id] [--json]

Doctor est uniquement diagnostique ; il signale les racines manquantes, les incohérences de métadonnées et les états invalides du registre local sans modifier le magasin.

Référencement des magasins depuis un projet

Un dépôt de projet peut déclarer quels magasins alimentent son travail dans openspec/config.yaml :

schema: spec-driven
references:
  - team-context

Dès lors, la sortie openspec instructions dans ce dépôt (à la fois les surfaces par artefact et apply, modes JSON et humain) transporte un index des spécifications de chaque magasin référencé — identifiants de spécification, un résumé d'une ligne provenant de la section Objectif de chaque spécification, et la commande de récupération (openspec show <spec-id> --type spec --store <id>). L'index est construit en direct à partir de la copie enregistrée à chaque exécution ; le contenu des spécifications n'est jamais copié dans la sortie.

Les références sont un contexte en lecture seule. Elles ne changent jamais l'emplacement où les commandes agissent : le travail reste dans la racine propre du dépôt, et l'écriture dans un magasin référencé reste une action explicite --store. Une référence qui ne peut pas être résolue (par exemple, un magasin non enregistré sur cette machine) se dégrade en un avertissement dans l'index avec la correction exacte, et les instructions sont toujours générées. openspec doctor rapporte la santé des références en un seul endroit.

Enregistrement de la source de clonage d'un magasin

Un magasin peut enregistrer sa source de clonage canonique dans son fichier d'identité engagé, afin que l'intégration ne se termine jamais par "enregistrer le magasin" :

openspec store setup team-context --path ~/openspec/team-context \
  --remote git@github.com:acme/team-context.git

Le distant est inscrit dans .openspec-store/store.yaml à l'intérieur du commit initial, donc chaque clone naît en le connaissant. Pour un magasin existant, modifiez store.yaml manuellement et engagez. store doctor affiche le distant enregistré (et l'origine Git observée de la copie) ; les conseils de partage de setup/register le nomment ; et register enregistre l'origine de la copie dans le registre local à la machine.

Une déclaration de référence peut également transporter la source de clonage, afin qu'un collègue qui n'a pas encore le magasin obtienne une correction complète et collable (git clone <remote> <path> && openspec store register <path> --id <id>) :

references:
  - { id: team-context, remote: "git@github.com:acme/team-context.git" }

L'enregistrement d'un distant n'est pas une synchronisation : OpenSpec ne clone, ne tire ni ne pousse jamais de lui-même.

Déclaration d'un magasin par défaut

Un dépôt dont la planification est entièrement externalisée — aucun openspec/specs/ ou openspec/changes/ local — peut déclarer son magasin une fois au lieu de passer --store à chaque commande :

# openspec/config.yaml (le seul fichier sous openspec/)
store: team-context

Les commandes normales se résolvent alors automatiquement vers le magasin déclaré ; la bannière de racine et le bloc JSON root rapportent source: "declared" avec l'identifiant du magasin, et les indices imprimés portent toujours --store <id>. La déclaration est un secours, jamais une substitution : --store explicite gagne toujours, et un répertoire avec de vrais dossiers de planification ignore le pointeur (avec un avertissement). Pour convertir un dépôt pointeur en une racine OpenSpec locale, supprimez la ligne store: et exécutez openspec init — init refuse de créer l'infrastructure tant que la déclaration est présente.

Une variante au niveau de la machine couvre tous les dépôts à la fois : openspec config set defaultStore <id> (voir Configuration). Elle n'est consultée qu'après que --store, une racine locale et un pointeur de projet ont tous échoué à se résoudre ; la bannière de racine et le bloc JSON root rapportent alors source: "global_default".

Doctor (santé des relations)

Une seule question en lecture seule, un seul endroit : la racine OpenSpec est-elle saine, et les magasins qu'elle référence sont-ils disponibles sur cette machine ?

openspec doctor [--store <id>] [--json]

Le rapport distingue la santé de la racine, la santé des métadonnées des magasins (y compris une note lorsque la distante enregistrée et l'origine du checkout divergent, et une note lorsque le checkout du magasin a dérivé par rapport à sa dernière référence de suivi amont récupérée), et la santé des références (les mêmes instructions de diagnostic que show, avec des correctifs de clonage pour les références non résolues). Les constats de santé, quelle que soit leur gravité, se terminent avec le code 0 — les agents lisent les tableaux status ; seules les défaillances de commande (aucune racine, magasin inconnu) se terminent avec le code 1. Doctor ne clone, ne synchronise et ne répare jamais. Pour obtenir l'ensemble assemblé lui-même plutôt que sa santé, utilisez openspec context.

Contexte de travail (l'ensemble assemblé)

Tout ce à quoi ce travail est lié par les déclarations OpenSpec, dans un seul ensemble de travail : la racine OpenSpec et les magasins qu'elle référence.

openspec context [--store <id>] [--json] [--code-workspace <path> [--force]]

Le résumé JSON est consommable par les agents (chaque magasin référencé disponible porte sa recette de récupération ; les membres non résolus portent les mêmes instructions de correctifs et doctor show). --code-workspace écrit en outre un fichier d'espace de travail VS Code contenant la racine ainsi que les magasins référencés disponibles (dossiers ref:<id>) — la seule écriture que cette commande effectue, refusée sans --force si le fichier existe. Les membres indisponibles sont signalés, jamais devinés.

« Contexte de travail » désigne l'ensemble assemblé ; le champ context: dans openspec/config.yaml est le contexte du projet injecté dans les instructions — deux choses différentes. openspec doctor répond si l'ensemble est sain ; openspec context répond à quoi l'ensemble correspond.

Ensembles de travail personnels

Bêta. Les ensembles de travail font partie de la nouvelle surface bêta ; les commandes, les drapeaux et les formats de fichiers peuvent changer entre les versions. Pour le guide pas à pas, consultez le guide des magasins.

Un ensemble de travail est une vue personnelle et nommée des dossiers sur lesquels vous travaillez ensemble — une racine de planification plus tout ce que vous choisissez — conservée sur votre machine et rouverte par nom dans votre outil. Il est purement local : jamais commité, jamais partagé, jamais dérivé de déclarations, et la suppression d'un ensemble ne touche jamais un dossier membre.

openspec workset create [name] [--member <path> | --member <name>=<path>]... [--tool <id>] [--json]
openspec workset list [--json]
openspec workset open <name> [--tool <id>]
openspec workset remove <name> [--yes] [--json]

create exécute un flux guidé court (ou accepte les drapeaux --member de manière non interactive ; le premier membre est le principal — les sessions démarrent là). open lance l'outil choisi : les éditeurs (VS Code, Cursor) ouvrent une fenêtre avec chaque membre et reviennent ; les agents CLI (Claude Code, codex) prennent le contrôle de ce terminal en tant que session avec chaque membre attaché et sans invite pré-remplie, se terminant lorsque vous quittez. Un dossier membre manquant au moment de l'ouverture est ignoré avec une note ; le reste s'ouvre. La préférence d'outil enregistrée peut être remplacée à chaque ouverture avec --tool.

Prendre en charge un nouvel outil est une question de configuration, pas de code. Chaque outil suit l'un des deux styles de lancement — workspace-file (lancé avec le .code-workspace généré) ou attach-dirs (un drapeau d'attachement par membre) — et la clé openers dans le config.json global (ouvrez-le avec openspec config edit) ajoute des outils ou ajuste les intégrés par champ :

{
  "openers": {
    "zed": { "style": "workspace-file" },
    "claude": { "attach_flag": "--dir" }
  }
}

Tout l'état des ensembles de travail se trouve sous le dossier worksets/ du répertoire de données global (les vues enregistrées ainsi que les fichiers <name>.code-workspace générés, régénérés à chaque ouverture) ; la suppression de ce dossier efface toute trace.

---

Commandes de navigation

openspec list

Liste les modifications ou les spécifications de votre projet.

openspec list [options]

Options :

Option	Description
--specs	Liste les spécifications au lieu des modifications
--changes	Liste les modifications (par défaut)
--sort <order>	Trie par recent (par défaut) ou name
--json	Sortie au format JSON

Exemples :

# List all active changes
openspec list

# List all specs
openspec list --specs

# JSON output for scripts
openspec list --json

Sortie (texte)：

Changes:
  add-dark-mode     No tasks      just now

---

openspec view

Affiche un tableau de bord interactif pour explorer les spécifications et les modifications.

openspec view

Ouvre une interface basée sur le terminal pour naviguer dans les spécifications et les modifications de votre projet.

---

openspec show

Affiche les détails d'une modification ou d'une spécification.

openspec show [item-name] [options]

Arguments :

Argument	Requis	Description
item-name	Non	Nom de la modification ou de la spécification (invite si omis)

Options :

Option	Description
--type <type>	Spécifie le type : change ou spec (détection automatique si non ambigu)
--json	Sortie au format JSON
--no-interactive	Désactive les invites

Options spécifiques aux modifications :

Option	Description
--deltas-only	Affiche uniquement les spécifications delta (mode JSON)

Options spécifiques aux spécifications :

Option	Description
--requirements	Affiche uniquement les exigences, exclut les scénarios (mode JSON)
--no-scenarios	Exclut le contenu des scénarios (mode JSON)
-r, --requirement <id>	Affiche une exigence spécifique par index à base 1 (mode JSON)

Exemples :

# Interactive selection
openspec show

# Show a specific change
openspec show add-dark-mode

# Show a specific spec
openspec show auth --type spec

# JSON output for parsing
openspec show add-dark-mode --json

---

Commandes de validation

openspec validate

Valide les modifications et les spécifications pour détecter les problèmes structurels, et vérifie les exigences MODIFIED d'une modification par rapport aux spécifications principales qu'elles remplaceront.

openspec validate [item-name] [options]

Une modification avec zéro delta de spécification échoue la validation, sauf si son .openspec.yaml déclare skip_specs: true (pour les refactorisations pures, le travail d'outillage ou de documentation — voir Recette 5).

Arguments :

Argument	Obligatoire	Description
item-name	Non	Élément spécifique à valider (invite à la saisie si omis)

Options :

Option	Description
--all	Valide toutes les modifications et spécifications
--changes	Valide toutes les modifications
--specs	Valide toutes les spécifications
--archived	Valide que les modifications archivées ont toutes leurs tâches terminées (pour le linting pré-commit)
--type <type>	Spécifie le type lorsque le nom est ambigu : change ou spec
--strict	Active le mode de validation strict
--json	Sortie au format JSON
--concurrency <n>	Nombre maximal de validations parallèles (par défaut : 6, ou variable d'environnement OPENSPEC_CONCURRENCY)
--no-interactive	Désactive les invites

--archived constitue une portée à part entière : il ne valide pas les deltas de spécification (déjà appliqués lors de l'archivage), il vérifie que chaque modification sous changes/archive/ a toutes les cases à cocher de son tasks.md cochées, en quittant avec un code non nul si certaines ne le sont pas. Cela détecte les modifications archivées avec du travail inachevé — pratique dans un hook pré-commit.

Exemples :

# Validation interactive
openspec validate

# Valider une modification spécifique
openspec validate add-dark-mode

# Valider toutes les modifications
openspec validate --changes

# Valider tout avec une sortie JSON (pour CI/scripts)
openspec validate --all --json

# Validation stricte avec parallélisme accru
openspec validate --all --strict --concurrency 12

# Échouer si une modification archivée a encore des tâches non cochées
openspec validate --archived

Sortie (texte) :

Validating add-dark-mode...
  ✓ proposal.md valid
  ✓ specs/ui/spec.md valid
  ⚠ design.md: missing "Technical Approach" section

1 warning found

Sortie (JSON)：

{
  "version": "1.0.0",
  "results": {
    "changes": [
      {
        "name": "add-dark-mode",
        "valid": true,
        "warnings": ["design.md: missing 'Technical Approach' section"]
      }
    ]
  },
  "summary": {
    "total": 1,
    "valid": 1,
    "invalid": 0
  }
}

---

Commandes de cycle de vie

openspec archive

Archive une modification terminée et fusionne les spécifications delta dans les spécifications principales.

openspec archive [change-name] [options]

Arguments :

Argument	Obligatoire	Description
change-name	Non	Modification à archiver (invite à la saisie si omis ; obligatoire si rien ne peut répondre à l'invite)

Options：

Option	Description
-y, --yes	Ignore les invites de confirmation. Obligatoire si rien ne peut y répondre — un agent IA, un job CI, ou toute exécution avec l'entrée standard fermée
--skip-specs	Ignore les mises à jour des spécifications pour une seule exécution d'archivage. Une modification qui n'a définitivement aucun delta de spécification doit déclarer skip_specs: true dans son .openspec.yaml — elle s'archive sans option
--no-validate	Ignore la validation (nécessite une confirmation). Désactive également la retraite de capacité — sans verdict du validateur, rien n'est retiré

Exemples :

# Archivage interactif (demande quelle modification, puis confirme)
openspec archive

# Archiver une modification spécifique
openspec archive add-dark-mode

# Archiver sans invites (agents, CI, scripts)
openspec archive add-dark-mode --yes

# Archiver une modification d'outillage qui n'affecte pas les spécifications
openspec archive update-ci-config --skip-specs

Retirer une capacité : Ajoutez le marqueur de retraite aux métadonnées de la modification :

# openspec/changes/retire-legacy/.openspec.yaml
schema: spec-driven
retire_capabilities: true

Puis archivez la modification normalement :

openspec archive retire-legacy --yes

Lorsque la modification supprime la dernière exigence d'une capacité, OpenSpec supprime son spec.md actif. Les autres deltas de capacité dans la même modification mettent toujours à jour leurs spécifications principales. Sans le marqueur, l'archivage s'arrête avant de modifier des fichiers et vous indique de l'ajouter.

Ce qu'il fait :

1. Valide la modification (sauf avec --no-validate)
2. Demande une confirmation (sauf avec --yes)
3. Réserve la destination d'archivage avant de modifier toute spécification principale
4. Valide et fusionne les spécifications delta actives dans openspec/specs/ — une capacité dont la dernière exigence est supprimée par la modification est retirée, et son fichier de spécification supprimé, mais uniquement lorsque le .openspec.yaml de la modification déclare retire_capabilities: true à côté de son schema:
5. Déplace le dossier de modification vers openspec/changes/archive/YYYY-MM-DD-<name>/
6. Si une mutation de spécification ou le déplacement final échoue avant qu'un archivage complet ne soit sécurisé, restaure les spécifications et laisse ou renvoie la modification à son chemin actif
7. Si une copie de secours vérifiée est complétée mais que le nettoyage de la source en attente échoue, conserve l'archivage complet et l'état des spécifications engagées pour récupération

Sans terminal : un agent IA, un job CI, ou toute exécution avec l'entrée standard fermée ne peut pas répondre à l'étape 2, donc l'archivage s'arrête avant de toucher quoi que ce soit, quitte avec le code 1, et indique la commande à relancer — openspec archive <name> --yes, avec toutes les autres options que vous avez passées. Passez --yes (et le nom de la modification) dès le départ pour éviter l'aller-retour.

---

Commandes de workflow

Ces commandes prennent en charge le workflow OPSX piloté par les artefacts. Elles sont utiles à la fois pour les humains qui vérifient la progression et pour les agents qui déterminent les prochaines étapes.

openspec new change

Crée un répertoire de changement et des métadonnées facultatives vérifiées dans la racine OpenSpec résolue.

openspec new change <name> [options]

Les noms de changement doivent utiliser le kebab-case en minuscules : lettres minuscules, chiffres et traits d'union simples. Ils ne peuvent pas contenir d'espaces, de traits de soulignement, de lettres majuscules, de traits d'union consécutifs, ni de traits d'union en début ou en fin. Un chiffre en tête est autorisé, vous pouvez donc préfixer les noms pour ordonner ou hiérarchiser les changements, par exemple 100-add-feature ou 00001-add-auth.

Options :

Option	Description
--description <text>	Description à ajouter à index.md
--goal <text>	Métadonnées d'objectif facultatives à stocker avec le changement
--schema <name>	Schéma de workflow à utiliser
--store <id>	Identifiant de store à utiliser comme racine OpenSpec (un store est un dépôt OpenSpec autonome que vous avez enregistré)
--json	Sortie JSON

Exemples :

openspec new change add-billing-api
openspec new change add-billing-api --store team-context --json

openspec status

Affiche l'état d'achèvement des artefacts pour un changement.

openspec status [options]

Options :

Option	Description
--change <id>	Nom du changement (invite si omis)
--schema <name>	Remplacement de schéma (détecté automatiquement à partir de la configuration du changement)
--json	Sortie en JSON

Exemples :

# Vérification interactive de l'état
openspec status

# État pour un changement spécifique
openspec status --change add-dark-mode

# JSON pour utilisation par un agent
openspec status --change add-dark-mode --json

Sortie (texte) :

Change: add-dark-mode
Schema: spec-driven
Progress: 2/4 artifacts complete

[x] proposal
[x] specs
[ ] design
[-] tasks (blocked by: design)

Un changement qui déclare skip_specs: true affiche son étape de spécifications comme [~] specs (skipped: change declares skip_specs) et l'exclut du compteur de progression.

Sortie (JSON) :

{
  "changeName": "add-dark-mode",
  "schemaName": "spec-driven",
  "isPlanningComplete": false,
  "isComplete": false,
  "applyRequires": ["tasks"],
  "artifacts": [
    {"id": "proposal", "outputPath": "proposal.md", "status": "done", "requires": []},
    {"id": "specs", "outputPath": "specs/**/*.md", "status": "done", "requires": ["proposal"]},
    {"id": "design", "outputPath": "design.md", "status": "ready", "requires": ["proposal"]},
    {"id": "tasks", "outputPath": "tasks.md", "status": "blocked", "requires": ["specs", "design"], "missingDeps": ["design"]}
  ]
}

isPlanningComplete indique si chaque artefact de planification non ignoré existe ; les artefacts ignorés sont considérés comme satisfaits sans être créés. Il ne signale pas si les tâches de mise en œuvre sont terminées. isComplete est conservé comme alias de compatibilité avec la même valeur.

Les artefacts sont répertoriés dans l'ordre des dépendances - une dépendance n'apparaît jamais après un élément qui en dépend - et les artefacts qui deviennent prêts en même temps (les specs et design de spec-driven n'ont besoin que de proposal) conservent l'ordre déclaré par le schéma plutôt qu'un ordre alphabétique. Ainsi, la première entrée ready est l'artefact à écrire ensuite.

---

openspec instructions

Obtenez des instructions enrichies pour créer un artefact ou appliquer des tâches. Utilisé par les agents IA pour comprendre quoi créer ensuite.

openspec instructions [artifact] [options]

Arguments :

Argument	Requis	Description
artifact	Non	Identifiant d'artefact, ou surface d'entrée de workflow : apply ou archive

Options :

Option	Description
--change <id>	Nom du changement (requis en mode non interactif)
--schema <name>	Remplacement de schéma
--json	Sortie en JSON

Cas particuliers : Utilisez apply pour obtenir les instructions de mise en œuvre des tâches. Utilisez archive pour récupérer les entrées d'archive actuelles en lecture seule (context et operationGuidance) pour un changement valide ; il n'archive ni ne modifie rien.

Exemples :

# Obtenir les instructions pour le prochain artefact
openspec instructions --change add-dark-mode

# Obtenir les instructions pour un artefact spécifique
openspec instructions design --change add-dark-mode

# Obtenir les instructions apply/mise en œuvre
openspec instructions apply --change add-dark-mode

# Obtenir les entrées d'opération d'archive actuelles sans archiver
openspec instructions archive --change add-dark-mode --json

# JSON pour utilisation par un agent
openspec instructions design --change add-dark-mode --json

La sortie comprend :

• Contenu du modèle pour l'artefact
• Contexte du projet à partir de la configuration
• Contenu des artefacts dépendants
• Règles par artefact à partir de la configuration
• Contexte actuel du projet et directives d'opération correspondantes pour apply/archive

Les entrées d'opération sont lues à partir du dépôt résolu ou du store sélectionné à chaque invocation. Le contexte du projet est une entrée requise au niveau de l'invite : les agents le lisent et appliquent les faits, conventions et contraintes pertinents du projet. Les directives d'opération sont un conseil additif facultatif : les agents considèrent chaque entrée et ne suivent que les entrées applicables et compatibles avec le workflow intégré. Les deux champs restent séparés des choix utilisateur explicites, de l'état contrôlé par la CLI, des instructions intégrées et des règles d'artefact. Les contextes contradictoires sont signalés ; les directives conflictuelles ou inapplicables ne sont pas suivies et la raison est expliquée. Ce sont des contrats comportementaux pour les agents générés, pas des vérifications CLI exécutoires. instructions archive ne renvoie que le changement sélectionné, les entrées facultatives et les métadonnées racine ; il n'inclut pas le workflow d'archive statique.

Pour un artefact ignoré via skip_specs: true, la sortie est uniquement un avertissement (JSON ajoute les champs skipped/warning) — l'artefact ne doit pas être créé.

---

openspec templates

Affiche les chemins de modèles résolus pour tous les artefacts d'un schéma.

openspec templates [options]

Options :

Option	Description
--schema <name>	Schéma à inspecter (défaut : spec-driven)
--json	Sortie en JSON

Exemples :

# Afficher les chemins de modèles pour le schéma par défaut
openspec templates

# Afficher les modèles pour un schéma personnalisé
openspec templates --schema my-workflow

# JSON pour utilisation programmatique
openspec templates --json

Sortie (texte) :

Schema: spec-driven

Templates:
  proposal  → ~/.openspec/schemas/spec-driven/templates/proposal.md
  specs     → ~/.openspec/schemas/spec-driven/templates/specs.md
  design    → ~/.openspec/schemas/spec-driven/templates/design.md
  tasks     → ~/.openspec/schemas/spec-driven/templates/tasks.md

---

openspec schemas

Liste les schémas de workflow disponibles avec leurs descriptions et flux d'artefacts.

openspec schemas [options]

Options :

Option	Description
--json	Sortie en JSON
--store <id>	Utiliser un store enregistré comme racine OpenSpec

Exemple :

openspec schemas

Sortie :

Available schemas:

  spec-driven (package)
    The default spec-driven development workflow
    Flow: proposal → specs → design → tasks

  my-custom (project)
    Custom workflow for this project
    Flow: research → proposal → tasks

---

Commandes de schéma

Commandes pour créer et gérer des schémas de workflow personnalisés.

openspec schema init

Créer un nouveau schéma local au projet.

openspec schema init <name> [options]

Arguments :

Argument	Requis	Description
name	Oui	Nom du schéma (kebab-case)

Options :

Option	Description
--description <text>	Description du schéma
--artifacts <list>	IDs d'artefacts séparés par des virgules (par défaut : proposal,specs,design,tasks)
--default	Définir comme schéma par défaut du projet
--no-default	Ne pas demander de définir comme schéma par défaut
--force	Écraser le schéma existant
--json	Sortie au format JSON

Exemples :

# Création interactive de schéma
openspec schema init research-first

# Non interactif avec des artefacts spécifiques
openspec schema init rapid \
  --description "Workflow d'itération rapide" \
  --artifacts "proposal,tasks" \
  --default

Ce qu'il crée :

openspec/schemas/<name>/
├── schema.yaml           # Définition du schéma
└── templates/
    ├── proposal.md       # Template pour chaque artefact
    ├── specs.md
    ├── design.md
    └── tasks.md

---

openspec schema fork

Copier un schéma existant dans votre projet pour le personnaliser.

openspec schema fork <source> [name] [options]

Arguments :

Argument	Requis	Description
source	Oui	Schéma à copier
name	Non	Nouveau nom du schéma (par défaut : <source>-custom)

Options :

Option	Description
--force	Écraser la destination existante
--json	Sortie au format JSON

Exemple :

# Fork du schéma spec-driven intégré
openspec schema fork spec-driven my-workflow

---

openspec schema validate

Valider la structure et les modèles d'un schéma.

openspec schema validate [name] [options]

Arguments :

Argument	Requis	Description
name	Non	Schéma à valider (valide tous les schémas s'il est omis)

Options :

Option	Description
--verbose	Afficher les étapes détaillées de validation
--json	Sortie au format JSON

Exemple :

# Valider un schéma spécifique
openspec schema validate my-workflow

# Valider tous les schémas
openspec schema validate

---

openspec schema which

Afficher l'emplacement de résolution d'un schéma (utile pour déboguer la priorité).

openspec schema which [name] [options]

Arguments :

Argument	Requis	Description
name	Non	Nom du schéma

Options :

Option	Description
--all	Lister tous les schémas avec leurs sources
--json	Sortie au format JSON

Exemple :

# Vérifier d'où provient un schéma
openspec schema which spec-driven

Sortie :

spec-driven resolves from: package
  Source: /usr/local/lib/node_modules/@fission-ai/openspec/schemas/spec-driven

Priorité des schémas :

1. Projet : openspec/schemas/<name>/
2. Utilisateur : ~/.local/share/openspec/schemas/<name>/
3. Package : Schémas intégrés

---

Commandes de configuration

openspec config

Afficher et modifier la configuration globale d'OpenSpec.

openspec config <subcommand> [options]

Sous-commandes :

Sous-commande	Description
path	Afficher l'emplacement du fichier de configuration
list	Afficher tous les paramètres actuels
get <key>	Obtenir une valeur spécifique
set <key> <value>	Définir une valeur
unset <key>	Supprimer une clé
reset	Réinitialiser aux valeurs par défaut
edit	Ouvrir dans $EDITOR
profile [preset]	Configurer le profil de workflow de manière interactive ou via un préréglage

Exemples :

# Afficher le chemin du fichier de configuration
openspec config path

# Lister tous les paramètres
openspec config list

# Obtenir une valeur spécifique
openspec config get telemetry.enabled

# Définir une valeur (désactiver la télémétrie d'utilisation anonyme)
openspec config set telemetry.enabled false

# Définir explicitement une valeur de chaîne
openspec config set user.name "Mon Nom" --string

# Supprimer un paramètre personnalisé
openspec config unset user.name

# Définir un magasin par défaut au niveau machine (racine de repli lorsqu'il n'y a pas de --store,
# racine locale ou magasin de projet : le pointeur se résout)
openspec config set defaultStore team-plans

# Réinitialiser toute la configuration
openspec config reset --all --yes

# Éditer la configuration dans votre éditeur
openspec config edit

# Configurer le profil avec un assistant basé sur les actions
openspec config profile

# Préréglage rapide : passer les workflows à core (conserve le mode de livraison)
openspec config profile core

Désactivation de la télémétrie : telemetry.enabled est activé par défaut lorsqu'il n'est pas défini (modèle de désactivation). Définissez-le sur false pour désactiver les statistiques d'utilisation anonymes et la vérification de version openspec update. Les variables d'environnement ont la priorité sur la configuration : OPENSPEC_TELEMETRY=0, DO_NOT_TRACK=1, et une valeur vraie de CI (par ex. true/1/yes) désactive toujours la télémétrie indépendamment de la valeur de configuration.

openspec config profile commence par un résumé de l'état actuel, puis vous permet de choisir :

• Changer la livraison + les workflows
• Changer uniquement la livraison
• Changer uniquement les workflows
• Conserver les paramètres actuels (quitter)

Si vous conservez les paramètres actuels, aucun changement n'est écrit et aucune invite de mise à jour n'est affichée. S'il n'y a pas de modifications de configuration mais que les fichiers du projet actuel sont désynchronisés par rapport à votre profil global/livraison, OpenSpec affichera un avertissement et suggérera openspec update. Appuyer sur Ctrl+C annule également proprement le flux (pas de trace de pile) et quitte avec le code 130. Dans la liste de contrôle des workflows, [x] signifie que le workflow est sélectionné dans la configuration globale. Pour appliquer ces sélections aux fichiers du projet, exécutez openspec update (ou choisissez Apply changes to this project now? lorsque vous y êtes invité dans un projet).

Exemples interactifs :

# Mise à jour uniquement de la livraison
openspec config profile
# choisir : Change delivery only
# choisir la livraison : Skills only

# Mise à jour uniquement des workflows
openspec config profile
# choisir : Change workflows only
# basculer les workflows dans la liste de contrôle, puis confirmer

---

Commandes utilitaires

openspec feedback

Soumettre des commentaires sur OpenSpec. Crée un problème GitHub.

openspec feedback <message> [options]

Arguments :

Argument	Requis	Description
message	Oui	Résumé des commentaires ; le texte long est raccourci dans le titre du problème et conservé dans le corps

Options :

Option	Description
--body <text>	Détails supplémentaires inclus après le résumé

Prérequis : La CLI GitHub (gh) doit être installée et authentifiée.

Exemple :

openspec feedback "Ajouter le support pour les types d'artefacts personnalisés" \
  --body "Je souhaite définir mes propres types d'artefacts au-delà de ceux intégrés."

---

openspec completion

Gérer les complétions de shell pour la CLI OpenSpec.

openspec completion <subcommand> [shell]

Sous-commandes :

Sous-commande	Description
generate [shell]	Générer le script de complétion vers stdout
install [shell]	Installer la complétion pour votre shell
uninstall [shell]	Supprimer les complétions installées

Shells pris en charge : bash, zsh, fish, powershell

Exemples :

# Installer les complétions (détection automatique du shell)
openspec completion install

# Installer pour un shell spécifique
openspec completion install zsh

# Générer un script pour une installation manuelle (bash)
openspec completion generate bash > ~/.bash_completion.d/openspec

# Désinstaller
openspec completion uninstall

Windows (PowerShell) : Installer les complétions pour l'hôte PowerShell actuel :

$env:PROFILE = $PROFILE
openspec completion install powershell
. $PROFILE

$env:PROFILE indique à OpenSpec quel profil configurer dans cette session. L'installateur crée les répertoires de profil manquants et ajoute un bloc géré qui charge OpenSpecCompletion.ps1. Le rechargement du profil active immédiatement les complétions.

Pour désinstaller de l'hôte actuel, exécutez :

$env:PROFILE = $PROFILE
openspec completion uninstall powershell

Redémarrez PowerShell après la désinstallation pour effacer les complétions de la session actuelle.

Les complétions sont optionnelles. La CLI les mentionne une seule fois, sur stderr, la première fois que vous exécutez une commande dans un terminal interactif, et jamais ensuite — elle reste également silencieuse si vous avez déjà installé les complétions. Définissez OPENSPEC_NO_COMPLETIONS=1 pour supprimer entièrement cette astuce.

---

Codes de sortie

Code	Signification
0	Succès
1	Erreur (échec de validation, fichiers manquants, etc.)

---

Variables d'environnement

Variable	Description
OPENSPEC_TELEMETRY	Définir sur 0 pour désactiver la télémétrie et la vérification de version openspec update (remplace telemetry.enabled dans la configuration globale)
DO_NOT_TRACK	Définir sur 1 pour désactiver la télémétrie et la vérification de version openspec update (signal DNT standard ; remplace la configuration)
OPENSPEC_CONCURRENCY	Concurrence par défaut pour la validation en masse (par défaut : 6)
EDITOR ou VISUAL	Éditeur pour openspec config edit
NO_COLOR	Désactiver la sortie colorée lorsqu'elle est définie
OPENSPEC_NO_ANIMATION	Désactiver l'animation de bienvenue openspec init lorsqu'elle est définie
OPENSPEC_NO_COMPLETIONS	Définir sur 1 pour supprimer l'astuce unique concernant les complétions de shell
OPENSPEC_NO_UPDATE_CHECK	Désactiver la vérification openspec update pour une CLI publiée plus récente lorsqu'elle est définie (toute valeur, y compris vide). Également ignoré lorsque CI est défini (sauf si false/0/no/off) ou NODE_ENV=test
npm_config_registry	Registre interrogé par la vérification de version openspec update. Doit être une URL http(s) sinon il revient à https://registry.npmjs.org. Aucun fichier .npmrc n'est lu

---

Documentation connexe

• Commands - Commandes slash IA (/opsx:propose, /opsx:apply, etc.)
• Workflows - Modèles courants et quand utiliser chaque commande
• Customization - Créer des schémas et des modèles personnalisés
• Getting Started - Guide d'installation pour les nouveaux utilisateurs