CLI

Les commandes terminal openspec.

Commandes

Configuration

Commande	Fonction
`openspec init`	Initialiser OpenSpec dans un projet.
`openspec update`	Mettre à jour les fichiers d'instructions installés d'OpenSpec.
`openspec config`	Afficher et modifier la configuration globale.

Changements et spécifications

Commande	Fonction
`openspec list`	Lister les changements, ou les spécifications avec `--specs`.
`openspec show`	Afficher un changement ou une spécification, au format markdown ou JSON.
`openspec view`	Tableau de bord sur un seul écran des spécifications et des changements.
`openspec validate`	Vérifier les changements et les spécifications pour des problèmes structurels.
`openspec archive`	Déplacer un changement terminé vers l'archive et mettre à jour les spécifications principales.

Flux de travail et schémas

Votre agent exécute la plupart de ces commandes pendant le flux de travail.

Commande	Fonction
`openspec new`	Créer un nouveau répertoire de changement.
`openspec status`	Statut d'achèvement des artefacts pour un ou chaque changement actif.
`openspec instructions`	Instructions pour créer un artefact, l'appliquer ou l'archiver.
`openspec templates`	Chemins de modèles résolus pour les artefacts d'un schéma.
`openspec schemas`	Lister les schémas de flux de travail disponibles.
`openspec schema`	Inspecter, dupliquer (fork) ou créer un schéma (expérimental).

Multi-dépôt (bêta)

Commande	Fonction
`openspec store`	Créer et gérer des magasins : dépôts OpenSpec autonomes enregistrés sur votre machine.
`openspec doctor`	Signaler l'état de santé des relations pour la racine OpenSpec résolue.
`openspec context`	Afficher le contexte de travail pour la racine OpenSpec résolue.
`openspec workset`	Composer, conserver et ouvrir des vues de travail personnelles.

Utilitaires

Commande	Fonction
`openspec version`	Signaler la version installée et éventuellement vérifier la disponibilité d'une mise à jour.
`openspec install`	Installer le `openspec` autonome, qui fonctionne sans Node.js.
`openspec feedback`	Soumettre des commentaires sur OpenSpec.
`openspec completion`	Installer ou générer les complétions de shell.

Obsolète

Commande	Fonction
`openspec change`	Forme nominale de show, list et validate pour les changements. Le CLI avertit et renvoie vers les commandes à verbe en premier.
`openspec spec`	Forme nominale de show, list et validate pour les spécifications, avec le même avertissement.

Chaque commande accepte -h, --help. La commande openspec seule accepte également :

-V, --version : afficher la version du CLI.
--no-color : désactiver la sortie en couleur.

openspec init

Initialise OpenSpec dans un projet.

bash

openspec init                        # répertoire actuel, sélecteur interactif d'outils
openspec init --tools claude,cursor  # configurer des outils spécifiques, sans invites
openspec init --tools none           # structure openspec/ uniquement, aucun fichier d'outil

Sans --tools, init vous invite à sélectionner des outils dans un terminal interactif. En dehors d'un terminal, il configure les outils détectés dans le projet. Si aucun n'est détecté, il quitte avec le code 1 et liste les identifiants valides.

Dépôts de type store-only

Lorsque openspec/config.yaml contient une ligne store: et que le dépôt n'a pas de specs ou de changements locaux, exécutez init depuis la racine du dépôt :

bash

# installer les fichiers d'intégration Claude Code dans le dépôt de code
openspec init --tools claude

Fichiers d'intégration : écrits dans le dépôt de code.
openspec/config.yaml : préservé octet par octet.
openspec/specs/ et openspec/changes/ : non créés dans le dépôt de code.

Exécuter init depuis un sous-répertoire quitte avec le code 1 et vous indique de l'exécuter depuis la racine du dépôt. --language quitte également avec le code 1 car la langue doit être configurée dans le store externe. Exécutez init à la racine du store ou éditez directement cette configuration.

Arguments

Argument	Description
`path`	Le répertoire du projet à initialiser. Par défaut : répertoire actuel. Créé s'il n'existe pas.

Options

Option	Effet
`--tools <tools>`	Identifiants d'outils séparés par des virgules, `all` ou `none`. Ignore le sélecteur. Les identifiants sont listés dans Outils pris en charge.
`--language <language>`	Ajoute une instruction de langue à la configuration d'un nouveau projet. Rejeté lorsque la ligne `store:` du dépôt pointe vers un store externe.
`--force`	Supprime les fichiers des anciennes structures OpenSpec sans demander confirmation. En mode interactif, la confirmation du nettoyage est demandée au préalable.
`--profile <profile>`	Remplace le profil de configuration global pour cette exécution : `core` (l'ensemble de workflows standard) ou `custom` (les workflows enregistrés dans la configuration globale).
`--no-animation`	Affiche un écran de bienvenue statique au lieu de l'animé.

Sortie

Chaque outil sélectionné reçoit les compétences et commandes d'OpenSpec dans son propre répertoire :

▌ OpenSpec structure created
✔ Setup complete for Claude Code

OpenSpec Setup Complete

Created: Claude Code
6 skills and 6 commands in .claude/
Config: openspec/config.yaml (schema: spec-driven)

Getting started:
  Start your first change: /opsx:propose "your idea"

Restart your IDE for the new commands to take effect.

--tools none ne crée que openspec/config.yaml. Sur un projet déjà initialisé, init réécrit les fichiers installés sur place et le résumé affiche Refreshed: Claude Code avec Config: openspec/config.yaml (exists).

Codes de sortie

0 : configuration terminée.
1 : valeur --tools ou --profile invalide, une exécution non interactive sans outils détectés et sans --tools, ou une invocation store-only invalide.

openspec update

Met à jour les fichiers d'instructions installés par OpenSpec.

bash

openspec update             # actualiser les outils dont les fichiers sont plus anciens que le CLI
openspec update --force     # réécrire les fichiers même s'ils sont à jour
openspec update --dry-run   # lister ce qu'une mise à jour modifierait, sans rien changer

update identifie les outils configurés par init et compare leurs fichiers générés à la version du CLI. Lorsqu'une nouvelle version d'OpenSpec existe, il propose d'abord de mettre à niveau le CLI, puis relance l'opération avec la version mise à jour. Définissez OPENSPEC_NO_UPDATE_CHECK=1 pour ignorer cette vérification.

Arguments

Argument	Description
`path`	Le répertoire du projet à mettre à jour. Par défaut : répertoire actuel.

Options

Option	Effet
`--force`	Réécrit les fichiers de chaque outil configuré même s'ils sont à jour.
`--dry-run`	Signale chaque fichier que la mise à jour ajouterait, modifierait ou supprimerait, sans rien écrire. Aucune vérification de mise à niveau du CLI, aucune invite. À combiner avec `--force` pour prévisualiser une mise à jour forcée.
`--json`	Avec `--dry-run`, affiche le plan au format JSON. Sans `--dry-run`, quitte avec le code 1.

Prévisualiser une mise à jour

--dry-run planifie la mise à jour qu'une exécution non interactive effectuerait : le même chemin de code, avec chaque écriture et suppression enregistrée au lieu d'être effectuée. Chaque fichier que la vraie mise à jour toucherait est listé, y compris :

le déplacement de fichiers OpenSpec depuis l'ancien répertoire d'un outil (.kimi/ vers .kimi-code/, .windsurf/ vers .devin/, .codex/ et .agent/ vers .agents/) ;
l'enregistrement de la configuration globale lorsqu'une installation antérieure aux profils en reçoit une ;
la synchronisation des fichiers d'agent cloud de GitHub Copilot ;
avec --force, la configuration des outils trouvés uniquement dans des artefacts hérités et le nettoyage de ces artefacts, y compris les prompts globaux Codex retirés.

bash

openspec update --dry-run

2 file(s) would change:
  update  .claude/skills/openspec-propose/SKILL.md  (claude)
  add     ~/.config/openspec/config.json  (openspec)

--dry-run --json affiche le même plan sous forme d'un document JSON unique :

json

{
  "changes": [
    { "path": ".claude/skills/openspec-propose/SKILL.md", "action": "update", "tool": "claude" },
    { "path": "~/.config/openspec/config.json", "action": "add", "tool": "openspec" }
  ],
  "notes": [],
  "failures": []
}

Champ	Contenu
`changes[].path`	Chemin relatif au projet. Un fichier en dehors du projet, tel qu'une compétence globale ou la configuration globale, est affiché depuis votre répertoire personnel sous la forme `~/...`, ou sous forme de chemin absolu lorsqu'il est également en dehors du répertoire personnel.
`changes[].action`	`add`, `update` ou `delete`. Un fichier dont les nouveaux octets sont identiques aux anciens n'est pas listé.
`changes[].tool`	L'outil configuré auquel appartient le fichier, par exemple `claude`. Les fichiers qui appartiennent à OpenSpec lui-même plutôt qu'à un outil, la configuration globale et le nettoyage des artefacts hérités, sont `openspec`.
`notes[]`	`{ code, message }` pour une étape sur laquelle un utilisateur en terminal serait interrogé. `legacy-tool-directories` : un déplacement qu'une exécution interactive demande d'abord ; `changes` le liste comme effectué. `legacy-artifacts` : des fichiers de l'ancienne structure d'OpenSpec ont été trouvés, tels que des commandes slash `openspec-proposal.md` ou des blocs de marqueurs OpenSpec dans `AGENTS.md`. Sans `--force`, une mise à jour non interactive les laisse intacts, donc `changes` aussi ; `--dry-run --force` liste leur nettoyage. Vide pour une actualisation ordinaire.
`failures[]`	`{ tool, error }` pour chaque outil pour lequel la vraie mise à jour échouerait, y compris une écriture impossible : un répertoire à la place d'un fichier, un fichier à la place d'un répertoire, ou un fichier ou dossier sans permission d'écriture. Pour cet outil, `changes` s'arrête là où la vraie mise à jour s'arrête ; les autres outils sont toujours planifiés. Les échecs que le disque ne signale que lors de l'écriture, comme le manque d'espace, ne peuvent pas être prévus.

Un échec avant la planification, comme l'absence de répertoire OpenSpec, affiche toujours exactement un document JSON : le plan vide plus un tableau status avec severity, code (update_error) et message. Le code de sortie est 1.

Sortie

Lorsque les fichiers de chaque outil correspondent à la version du CLI :

✓ All 1 tool(s) up to date (v1.7.0)
  Tools: claude

Use --force to refresh files anyway.

Lorsque les fichiers d'un outil proviennent d'un CLI plus ancien (ou avec --force, qui affiche Force updating 1 tool(s): claude à la place) :

Updating 1 tool(s): claude (1.6.0 → 1.7.0)

✔ Updated Claude Code

✓ Updated: Claude Code (v1.7.0)
Tools: Claude Code

Restart your IDE for changes to take effect.

Dans un répertoire sans OpenSpec, update refuse :

✖ Error: No OpenSpec directory found. Run 'openspec init' first.

Codes de sortie

0 : fichiers mis à jour, ou tout est déjà à jour.
1 : aucun répertoire OpenSpec à ce chemin, ou la mise à jour a échoué.

openspec config

Affiche et modifie la configuration globale.

bash

openspec config list                  # voir les paramètres actuels
openspec config set delivery skills   # modifier une valeur
openspec config profile               # sélecteur interactif de workflows

Sous-commande	Description
`path`	Affiche l'emplacement du fichier de configuration.
`list`	Affiche tous les paramètres actuels.
`get <key>`	Affiche une valeur, brute et exploitable par script.
`set <key> <value>`	Définit une valeur, en convertissant son type.
`unset <key>`	Supprime une clé pour que sa valeur par défaut s'applique.
`reset`	Réinitialise toute la configuration aux valeurs par défaut.
`edit`	Ouvre le fichier de configuration dans `$EDITOR`.
`profile [preset]`	Configure le mode de livraison et les workflows.

La configuration est globale à votre machine, stockée au format JSON à l'emplacement indiqué par config path : $XDG_CONFIG_HOME/openspec/config.json si défini, sinon ~/.config/openspec/config.json (macOS, Linux) ou %APPDATA%\openspec\config.json (Windows). Chaque sous-commande accepte --scope <scope>, mais seul global fonctionne actuellement. Tout autre scope quitte avec le code 1 et le message Error: Project-local config is not yet implemented.

openspec config path

bash

openspec config path

/Users/you/.config/openspec/config.json

openspec config list

bash

openspec config list          # paramètres lisibles plus résumé du profil
openspec config list --json   # configuration brute au format JSON

Options

Option	Effet
`--json`	Affiche l'objet de configuration au format JSON.

Sortie

Chaque paramètre, puis un résumé du profil qui indique si les valeurs sont explicites ou par défaut :

featureFlags: {}
profile: core
delivery: both

Profile settings:
  profile: core (default)
  delivery: both (default)
  workflows: propose, explore, apply, update, sync, archive (from core profile)

openspec config get

bash

openspec config get delivery

Arguments

Argument	Description
`key`	La clé à lire. Les points permettent d'accéder aux valeurs imbriquées (`featureFlags.workspaces`).

Sortie

La valeur brute, prête pour les scripts. Les objets sont affichés en JSON compact :

both

Codes de sortie

0 : valeur affichée.
1 : la clé n'a pas de valeur, et rien n'est affiché.

openspec config set

bash

openspec config set delivery skills
openspec config set featureFlags.workspaces true

Arguments

Argument	Description
`key`	La clé à écrire, avec des points pour les valeurs imbriquées.
`value`	La nouvelle valeur. `true`/`false` deviennent des booléens, les chaînes numériques deviennent des nombres.

Options

Option	Effet
`--string`	Stocke la valeur sous forme de chaîne, sans conversion de type.
`--allow-unknown`	Autorise les clés non reconnues par le schéma.

Sortie

Set featureFlags.workspaces = true

Les clés inconnues et les valeurs invalides échouent avec le code 1 avant que quoi que ce soit soit enregistré :

Error: Invalid configuration key "bogus.key". Unknown top-level key "bogus".
Use "openspec config list" to see available keys.
Pass --allow-unknown to bypass this check.

Error: Invalid configuration - delivery: Invalid option: expected one of "both"|"skills"|"commands"

Si le fichier de configuration existe mais ne contient pas d'objet JSON, que ce soit parce qu'il n'est pas du JSON valide du tout ou parce que sa racine est autre chose comme null ou un tableau, config set, config unset et config profile quittent avec le code 1 et laissent le fichier inchangé. Corrigez-le avec openspec config edit, ou remplacez-le avec openspec config reset --all :

Error: /home/you/.config/openspec/config.json could not be parsed, so it was left unchanged.
Fix it with "openspec config edit", or reset it with "openspec config reset --all".

Tant qu'il n'est pas corrigé, la télémétrie et la vérification de mise à jour restent désactivées.

openspec config unset

bash

openspec config unset delivery

Supprime la clé pour que la valeur par défaut s'applique à nouveau. Les clés ayant des valeurs par défaut intégrées sont toujours considérées comme définies, donc cela signale un succès même si vous ne les avez jamais définies :

Unset delivery (reverted to default)

Une clé sans aucune valeur affiche Key "featureFlags.nothere" was not set. Les deux cas quittent avec le code 0. Un fichier de configuration qui ne peut pas être analysé quitte avec le code 1 à la place, comme pour config set.

openspec config reset

bash

openspec config reset --all      # demande confirmation
openspec config reset --all -y   # sans invite

Options

Option	Effet
`--all`	Requis. Réinitialise tout.
`-y, --yes`	Ignore l'invite de confirmation.

Sortie

Configuration reset to defaults

Sans --all, il quitte avec le code 1 et affiche la ligne d'utilisation.

Codes de sortie

0 : réinitialisation effectuée, ou vous avez répondu non à l'invite.
1 : --all manquant.
130 : invite annulée avec Ctrl-C.

openspec config edit

bash

openspec config edit

Ouvre le fichier de configuration dans $EDITOR (avec $VISUAL en secours), en le créant avec les valeurs par défaut d'abord s'il est absent. Lorsque l'éditeur se ferme, le fichier est validé. Un JSON invalide ou une configuration invalide quitte avec le code 1.

La valeur de l'éditeur peut contenir des arguments et des chemins entre guillemets, par exemple code --wait ou "/Applications/Sublime Text.app/Contents/SharedSupport/bin/subl" -w. Elle est découpée en mots sans shell, donc $VAR, ~ et ; sont transmis littéralement. Un éditeur qui ne peut pas démarrer, ou qui quitte avec un code non nul, affiche une erreur sur une ligne et quitte avec le code 1.

Sans éditeur configuré, il quitte avec le code 1 :

Error: No editor configured
Set the EDITOR or VISUAL environment variable to your preferred editor
Example: export EDITOR=vim

openspec config profile

bash

openspec config profile        # sélecteur interactif (nécessite un terminal)
openspec config profile core   # appliquer le préréglage core directement

Arguments

Argument	Description
`preset`	Nom de préréglage optionnel. Seul `core` existe. Il sélectionne les workflows core et conserve votre paramètre de livraison.

Sans préréglage, un sélecteur interactif affiche votre livraison et vos workflows actuels, vous permet de modifier l'un ou l'autre ou les deux (livraison : les deux, compétences uniquement ou commandes uniquement ; workflows : une liste de cases à cocher), affiche la différence, et dans un projet OpenSpec propose d'exécuter openspec update pour vous. En dehors d'un terminal, il quitte avec le code 1 :

Interactive mode required. Use `openspec config profile core` or set config via environment/flags.

Sortie

La configuration modifiée ne parvient aux projets que lorsqu'ils sont mis à jour :

Config updated. Run `openspec update` in your projects to apply.

Codes de sortie

0 : profil enregistré, ou vous avez conservé les paramètres actuels.
1 : préréglage inconnu, pas de terminal, ou le openspec update proposé a échoué.
130 : sélecteur annulé avec Ctrl-C.

openspec list

Liste les changements, ou les specs avec --specs.

bash

openspec list                    # active changes, most recently modified first
openspec list --archived         # archived changes
openspec list --all              # active and archived changes
openspec list --specs            # specs with requirement counts
openspec list --json             # machine-readable, includes the resolved root

Les lignes proviennent de openspec/changes/ et openspec/specs/ sous la racine résolue. La liste de changements par défaut ignore openspec/changes/archive/.

Options

Flag	Effet
`--specs`	Liste les specs au lieu des changements.
`--changes`	Liste les changements. C'est la valeur par défaut.
`--archived`	Liste uniquement les changements archivés. Ne peut pas être combiné avec `--specs`.
`--all`	Liste les changements actifs et archivés. Ne peut pas être combiné avec `--specs`. Prend le pas sur `--archived`.
`--sort <order>`	`recent` (dernier modifié en premier) ou `name`. Par défaut : `recent`. Les specs sont toujours triées par nom.
`--json`	Affiche du JSON au lieu du tableau.
`--store <id>`	Utilise un store enregistré comme racine OpenSpec au lieu du projet courant.

Sortie

Une ligne par changement : nom, statut des tâches, dernière modification. La colonne de statut affiche No tasks, 2/5 tasks ou ✓ Complete.

Changes:
  add-rate-limit     No tasks      just now

--all regroupe les changements actifs et archivés sous des en-têtes séparés. Chaque groupe utilise l'ordre de tri sélectionné :

Changes:
  add-rate-limit     No tasks      just now

Archived Changes:
  2026-08-10-add-login     ✓ Complete    2d ago

Specs:
  api     requirements 1

--json ajoute les comptes de tâches et un status de no-tasks, in-progress ou complete :

json

{
  "changes": [
    {
      "name": "add-rate-limit",
      "completedTasks": 0,
      "totalTasks": 0,
      "lastModified": "2026-08-11T13:44:40.171Z",
      "status": "no-tasks"
    }
  ],
  "root": {
    "path": "/Users/you/projects/my-app",
    "source": "nearest"
  }
}

Avec --archived ou --all, chaque objet changement inclut un booléen archived. Le tableau combiné utilise l'ordre de tri sélectionné. Un changement archivé peut encore avoir un statut in-progress lorsque son fichier de tâches suivi contient des tâches non cochées. Sans l'un ou l'autre de ces flags, la forme JSON reste inchangée.

Une liste vide affiche No active changes found., No archived changes found., No changes found. ou No specs found. et quitte toujours avec le code 0.

Un changement est un répertoire directement sous openspec/changes/. Contrairement aux specs, les changements ne peuvent pas être imbriqués dans un dossier de namespace. Un dossier comme changes/mobile/ qui enveloppe uniquement un changement (changes/mobile/refresh-token/) est listé avec le statut not a change, suivi d'un avertissement qui nomme les répertoires imbriqués. --json marque cette entrée avec un tableau nested et ajoute un tableau warnings au niveau supérieur. show, status, validate et archive refusent le dossier avec le même message. Pour corriger, déplacez le changement vers le haut et intégrez le namespace dans son nom :

bash

mv openspec/changes/mobile/refresh-token openspec/changes/mobile-refresh-token
rmdir openspec/changes/mobile

Codes de sortie

0 : liste affichée, même vide.
1 : aucune racine OpenSpec trouvée (en dehors d'un projet, sans --store).

openspec show

Affiche un changement ou une spec, en markdown ou JSON.

bash

openspec show add-rate-limit              # change: prints proposal.md
openspec show add-rate-limit --diff       # change: append requirement diffs
openspec show api                         # spec: prints spec.md
openspec show api --json --no-scenarios   # spec JSON without scenario text

Sans nom, show demande changement ou spec, puis liste les éléments à choisir. En dehors d'un terminal interactif, il quitte avec le code 1 et affiche les formes directes à la place.

Arguments

Argument	Description
`item-name`	Le changement ou la spec à afficher, par nom de dossier (`add-rate-limit`, `api`).

Options

Flag	Effet
`--json`	Affiche du JSON structuré au lieu du markdown brut.
`--type <change\|spec>`	Choisit le type lorsqu'un changement et une spec partagent un nom.
`--no-interactive`	Ne demande jamais : un nom manquant devient une erreur.
`--deltas-only`	JSON, changement : restreint la sortie aux deltas. Le JSON de changement est déjà limité aux deltas, donc la sortie correspond à `--json` simple.
`--requirements-only`	Alias déprécié pour `--deltas-only`. Avertit sur stderr.
`--diff`	Changement : ajoute les diffs de delta par exigence. Ignoré avec un avertissement pour les specs.
`--requirements`	JSON, spec : conserve le texte des exigences, vide les tableaux `scenarios`.
`--no-scenarios`	JSON, spec : même sortie que `--requirements`.
`-r, --requirement <id>`	JSON, spec : affiche une exigence par position basée sur 1. Ne peut pas être combiné avec `--requirements`.
`--store <id>`	Utilise un store enregistré comme racine OpenSpec au lieu du projet courant.

Les flags qui ne s'appliquent pas au type résolu sont ignorés avec un avertissement sur stderr.

Sortie

Le mode texte est un passage brut : un changement affiche son proposal.md, une spec affiche son spec.md.

# Add rate limiting

Pourquoi

Des clients non authentifiés peuvent saturer l'API.

Changements

Ajouter une limitation de débit par client à l'API publique.


Pour une modification, `--diff` affiche d'abord la proposition, puis une section `Specifications Changed (diffs)`. Les exigences ADDED incluent leur texte complet. Les exigences REMOVED conservent la Reason et la Migration rédigées. Les exigences RENAMED affichent FROM et TO. Les exigences MODIFIED affichent un diff unifié par rapport à l'exigence principale correspondante.

Si un en-tête MODIFIED ne correspond qu'après repliement de la casse ou des espaces, la sortie inclut à la fois le diff et un avertissement indiquant que la correspondance d'archive est exacte. Si la spec principale ou l'exigence est manquante, la sortie émet un avertissement et affiche le bloc delta complet. Un bloc MODIFIED sans différence textuelle affiche `(no textual changes)`.

Une modification avec `--json` a la forme delta :

```json
{
  "id": "add-rate-limit",
  "title": "Add rate limiting",
  "deltaCount": 1,
  "deltas": [
    {
      "spec": "api",
      "operation": "ADDED",
      "description": "Add requirement: The API SHALL limit each client to 100 requests per minute.",
      "requirement": {
        "name": "Rate limit",
        "text": "The API SHALL limit each client to 100 requests per minute.",
        "scenarios": [
          {
            "name": "Client exceeds the limit",
            "rawText": "- **WHEN** a client sends its 101st request within a minute\n- **THEN** the API responds 429"
          }
        ]
      },
      ...
    }
  ],
  "root": {
    "path": "/Users/you/projects/my-app",
    "source": "nearest"
  }
}

Chaque exigence porte son name, le texte d'en-tête après Requirement:. C'est le nom avec lequel l'archive fait correspondre les entrées MODIFIED, REMOVED et RENAMED. Chaque scénario porte son name, le texte d'en-tête après Scenario:. Une série de # fermants sur l'un ou l'autre en-tête ne fait pas partie du nom.

--json --diff conserve cette forme de niveau supérieur. Un delta MODIFIED gagne une chaîne diff, une chaîne warning, ou les deux. Les autres opérations sont inchangées. Une chaîne diff vide signifie que les blocs principal et delta sont textuellement identiques.

Une spec avec --json liste ses exigences avec leurs scénarios. Les exigences et les scénarios portent les mêmes champs name que le JSON de modification :

json

{
  "id": "api",
  "title": "api",
  "overview": "Public HTTP API behavior.",
  "requirementCount": 1,
  "requirements": [
    {
      "name": "Health endpoint",
      "text": "The API SHALL expose a health endpoint.",
      "scenarios": [
        {
          "name": "Health check succeeds",
          "rawText": "- **WHEN** a client requests GET /health\n- **THEN** the API responds 200"
        }
      ]
    }
  ],
  "metadata": {
    "version": "1.0.0",
    "format": "openspec"
  },
  "root": {
    "path": "/Users/you/projects/my-app",
    "source": "nearest"
  }
}

Un nom inconnu suggère des correspondances proches : Unknown item 'does-not-exist'. Did you mean: add-rate-limit, api?. Un nom qui correspond à la fois à une modification et à une spec provoque une erreur et demande --type.

Codes de sortie

0 : élément affiché.
1 : nom inconnu ou ambigu, aucun nom en dehors d'un terminal, un index -r hors plage, --requirements combiné avec -r, ou un delta ou une spec principale ne peut pas être lu pour --diff.

openspec view

Affiche un tableau de bord en un écran des specs et des modifications.

bash

openspec view   # résumé du projet en un écran

view affiche le tableau de bord une fois puis se termine. Il ne lit aucune frappe. Les modifications sont regroupées par avancement des tâches : Draft (aucune tâche pour le moment), Active (tâches en cours, avec une barre de progression et un pourcentage), Completed (toutes les tâches cochées). Les specs sont listées avec le nombre d'exigences, les plus grandes en premier.

Options

Drapeau	Effet
`--store <id>`	Utiliser un store enregistré comme racine OpenSpec au lieu du projet courant.

Sortie

OpenSpec Dashboard

════════════════════════════════════════════════════════════
Summary:
  ● Specifications: 1 specs, 1 requirements
  ● Draft Changes: 1
  ● Active Changes: 0 in progress
  ● Completed Changes: 0

Draft Changes
────────────────────────────────────────────────────────────
  ○ add-rate-limit

Specifications
────────────────────────────────────────────────────────────
  ▪ api                            1 requirement

════════════════════════════════════════════════════════════

Use openspec list --changes or openspec list --specs for detailed views

Une ligne de résumé Task Progress apparaît lorsqu'une modification a des tâches en cours.

Chaque modification active affiche également ses états de schéma et d'artefact sous sa barre de progression des tâches :

text

    └─ [spec-driven] proposal✓ specs→ design→ tasks✓

Marqueur	État de l'artefact
`✓`	Sa sortie existe. Un artefact tasks existant est considéré comme terminé même lorsque sa checklist n'est pas terminée.
`→`	Il est prêt à être créé.
Aucun marqueur	Il est bloqué par une dépendance manquante.
`(skipped)`	La modification le ignore.

Si un workflow ne peut pas être chargé, view affiche un avertissement et maintient visible la progression des tâches de cette modification. Exécutez openspec status --change <name> pour inspecter le workflow séparément. Après openspec view --store <id>, passez le même --store <id> à status.

Codes de sortie

0 : tableau de bord affiché.
1 : aucune racine OpenSpec trouvée (en dehors d'un projet, pas de --store).

openspec validate

Vérifie les modifications et les specs pour les problèmes structurels.

bash

openspec validate add-rate-limit   # une modification ou spec, par nom
openspec validate --all            # chaque modification et spec

Sans nom ni drapeau de masse, validate vous invite à choisir des éléments. En dehors d'un terminal interactif, il se termine avec le code 1 et affiche les drapeaux de masse à la place.

Arguments

Argument	Description
`item-name`	La modification ou la spec à valider, par nom de dossier (`add-rate-limit`, `api`).

Options

Drapeau	Effet
`--all`	Valider chaque modification et spec.
`--changes`	Valider chaque modification.
`--specs`	Valider chaque spec.
`--archived`	Vérifier l'avancement des tâches dans les modifications archivées, sans valider leurs deltas de spec appliqués.
`--strict`	Traiter les avertissements comme des échecs.
`--type <change\|spec>`	Choisir le type lorsqu'une modification et une spec portent le même nom.
`--json`	Afficher un rapport structuré au lieu de texte.
`--report <mode>`	Sortie de masse : `full` (par défaut) ou `findings`. Nécessite une portée de masse explicite.
`--concurrency <n>`	Nombre maximal de validations parallèles lors des exécutions de masse. Par défaut : `OPENSPEC_CONCURRENCY`, sinon 6.
`--no-interactive`	Ne jamais inviter : un nom manquant ou ambigu devient une erreur.
`--store <id>`	Utiliser un store enregistré comme racine OpenSpec au lieu du projet courant.

Sortie

Les exécutions de masse affichent une ligne de statut par élément, suivie des constatations éventuelles, et se terminent par les totaux :

✓ change/add-rate-limit
✓ spec/api
Totals: 2 passed, 0 failed (2 items)

Constatations liées aux cases à cocher des tâches

Les comptages de progression ne vérifient que les cases à cocher et rien d'autre, donc un fichier de tâches rédigé sous forme de puces simples est compté comme zéro tâche : openspec list et openspec status signalent aucun travail, et openspec archive n'a rien à signaler comme incomplet. Validate rapporte un WARNING sur chaque fichier de tâches suivi qui liste du travail sans case à cocher :

text

⚠ [WARNING] tasks.md: This change counts as 0 tasks: no line in its tracked task files is a checkbox, so "openspec list" and "openspec status" report no work and "openspec archive" has nothing to flag as incomplete. Write each task as "- [ ] 1.1 Description".

L'avertissement ne se déclenche que lorsque l'ensemble des fichiers suivis de la modification ne contient absolument aucune case à cocher. Un fichier de prose à côté d'une vraie checklist n'est pas signalé, et une modification en cours de rédaction conserve sa progression dès qu'une seule case à cocher existe. --strict transforme l'avertissement en échec. Le numéro de ligne figure dans le rapport --json.

Les blocs clôturés, les commentaires HTML, le front matter YAML et le code indenté ne sont pas analysés, donc un exemple de terminal collé n'est jamais pris pour une liste de tâches.

Constatations liées à la fusion d'archive

Pour les modifications, validate exécute le constructeur de fusion d'archive contre les specs principales actuelles sans écrire de fichiers. Il signale les conflits de fusion, tels qu'une cible MODIFIED manquante ou une exigence ADDED conflictuelle, comme INFO :

text

ℹ [INFO] api/spec.md: Archive would refuse this delta: api MODIFIED failed for header "### Requirement: Rate limiting" - not found

Ces constatations apparaissent même lorsque la validation réussit, dans les sorties texte et JSON. INFO ne modifie jamais le code de sortie, y compris sous --strict : une cible manquante peut appartenir à une modification sœur qui n'a pas encore été archivée. Les deltas déjà synchronisés dans les specs principales suivent les règles de fusion existantes de l'archive.

Cette vérification n'exécute pas la validation ultérieure de la spec fusionnée par l'archive ni les vérifications de retrait. Un rapport propre ne garantit pas que l'archivage réussira.

Si le précontrôle de fusion ne peut pas démarrer, une constatation INFO explique pourquoi. Les constatations de validation existantes et le code de sortie restent inchangés.

Un élément en échec liste chaque problème et la correction :

Change 'add-rate-limit' has issues
✗ [ERROR] api/spec.md: ADDED "Rate limiting" must include at least one scenario
Next steps:
  - Ensure change has deltas in specs/: use headers ## ADDED/MODIFIED/REMOVED/RENAMED Requirements
  - Each requirement MUST include at least one #### Scenario: block
  - Debug parsed deltas: openspec show add-rate-limit --json --deltas-only

--json affiche un rapport unique pour l'exécution :

json

{
  "items": [
    {
      "id": "add-rate-limit",
      "type": "change",
      "valid": true,
      "issues": [],
      "durationMs": 2
    }
  ],
  "summary": {
    "totals": {
      "items": 1,
      "passed": 1,
      "failed": 0
    },
    "byType": {
      "change": {
        "items": 1,
        "passed": 1,
        "failed": 0
      }
    }
  },
  "version": "1.0",
  "root": {
    "path": "/Users/you/projects/my-app",
    "source": "nearest"
  }
}

Les entrées issues portent un level de ERROR, WARNING ou INFO.

Codes de sortie

0 : chaque élément validé a réussi, y compris une portée de masse vide.
1 : un élément a échoué, la demande de rapport est invalide, openspec/config.yaml ne peut pas être lu ou n'est pas un YAML valide, ou l'exécution a échoué (par exemple un nom inconnu ou aucune racine OpenSpec). Une configuration qui ne peut pas être lue ou analysée arrête l'exécution avant qu'aucun élément ne soit vérifié ; avec --json, elle est signalée comme une entrée status unique avec le code unreadable_config ou unparseable_config.

--report full|findings

Sélectionne la sortie pour une portée de validation de masse explicite :

full : chaque élément. C'est la valeur par défaut. Un --report full explicite conserve la forme de sortie existante sans ajouter de métadonnées de rapport.
findings : uniquement les éléments avec des problèmes, y compris les éléments réussis avec des avertissements ou des informations. Chaque élément est toujours validé. Les totaux, le comportement en mode strict et les codes de sortie sont inchangés.

bash

openspec validate --all --report findings
openspec validate --archived --report findings --json

Portées

Drapeaux	`report.scope` des findings
`--all`	`all`
`--changes`	`changes`
`--specs`	`specs`
`--changes --specs`, ou `--all` avec l'un ou l'autre drapeau	`all`
`--archived`	`archived`

Les deux modes de rapport explicites rejettent un nom d'élément positionnel, une portée de masse manquante, ou des portées d'archive et actives combinées.

Sortie texte des findings

Sortie humaine : stdout affiche Scope: <scope> (<count> items), puis les totaux. Sans élément portant des problèmes :

text

Scope: all (2 items)
No item findings.
Totals: 2 passed, 0 failed (2 items)

Les libellés des éléments portant des problèmes, les libellés de sévérité, les chemins et les messages s'affichent sur stderr. Les échecs de portée active conservent la suggestion de relance Details: après les totaux. La bannière de racine existante et la sortie de progression peuvent précéder le rapport.

Sortie JSON des findings

--report findings --json affiche un document unique. Cet exemple contient deux éléments propres :

json

{
  "report": {
    "kind": "validation-findings",
    "version": "1.0",
    "scope": "all",
    "returnedItems": 0,
    "totalItems": 2
  },
  "itemFindings": [],
  "summary": {
    "totals": { "items": 2, "passed": 2, "failed": 0 },
    "byType": {
      "change": { "items": 1, "passed": 1, "failed": 0 },
      "spec": { "items": 1, "passed": 1, "failed": 0 }
    }
  },
  "root": { "path": "/Users/you/projects/my-app", "source": "nearest" }
}

report.kind et report.version : identifient la forme validation-findings, version 1.0. Il n'y a pas de version ou items de niveau supérieur.
report.returnedItems et report.totalItems : comptent respectivement les enregistrements retournés et tous les éléments validés.
itemFindings : enregistrements d'éléments complets dont le tableau issues est non vide. Inclut les problèmes ERROR, WARNING et INFO. Chaque enregistrement conserve id, type, valid, issues et durationMs. Les éléments archivés utilisent type: "change".
summary : totaux de l'exécution complète et comptages par type, et non comptages du sous-ensemble retourné. Une portée vide a des totaux à zéro et se termine avec le code 0.
root : les mêmes métadonnées de racine sélectionnée que le rapport complet.

Préservation des enregistrements : les éléments retournés conservent leur ordre du rapport complet et les champs additifs éventuels sur les éléments ou les problèmes. Le filtrage ne réécrit pas les messages ni les emplacements, y compris les champs optionnels line et column.

Échecs de commande : les échecs de sélection de racine ou de découverte d'éléments conservent le diagnostic status existant et se terminent avec le code 1. Ils ne retournent pas de rapport de findings complété ni un rapport vide réussi.

Demandes de rapport invalides

Les deux modes de rapport explicites rejettent ces demandes avant la sélection de la racine ou la découverte des éléments :

Une valeur de rapport non prise en charge, y compris une chaîne vide.
Un nom d'élément positionnel, même avec un drapeau de masse.
Aucune portée de masse explicite.
--archived combiné avec --all, --changes ou --specs.

En mode JSON, une demande rejetée se termine avec le code 1 avec uniquement un tableau status à un seul élément. Il n'a ni root ni charge utile de rapport :

bash

openspec validate --all --report bogus --json

json

{
  "status": [
    {
      "severity": "error",
      "code": "invalid_validation_report_request",
      "message": "Unknown validation report 'bogus'.",
      "fix": "Use --report full|findings with --all, --changes, --specs, or --archived, without an item name. Do not combine archived and active scopes."
    }
  ]
}

Le mode humain affiche l'erreur sur stderr. Un --report nu sans valeur est une erreur de syntaxe de Commander sur stderr, y compris avec --json ; il n'utilise pas cette enveloppe de diagnostic.

Filtrer un rapport complet en externe

Pour une vue JSON personnalisée, filtrez le rapport complet avec jq ou PowerShell. Ces exemples de script préservent le code de sortie de validation et laissent intacts les documents d'erreur de commande.

Dans Bash avec jq :

bash

if validation_json=$(openspec validate --all --json); then
  validation_exit=0
else
  validation_exit=$?
fi
printf '%s\n' "$validation_json" |
  jq 'if has("items") then .items |= map(select(.issues | length > 0)) else . end'
exit "$validation_exit"

Dans PowerShell :

powershell

$validationJson = openspec validate --all --json
$validationExit = $LASTEXITCODE
$validationReport = $validationJson | ConvertFrom-Json
if ($validationReport.PSObject.Properties.Name -contains 'items') {
  $validationReport.items = @($validationReport.items | Where-Object { $_.issues.Count -gt 0 })
}
$validationReport | ConvertTo-Json -Depth 100
exit $validationExit

Ces vues personnalisées conservent les clés du rapport complet mais omettent les éments propres. Elles ne sont ni des rapports full-v1 complets ni la forme versionnée --report findings.

openspec archive

Déplace un changement terminé vers l'archive et met à jour les spécifications principales.

bash

openspec archive add-rate-limit -y                # archive one change, merge its deltas
openspec archive add-rate-limit -y --skip-specs   # archive without touching the specs

Sans nom, archive vous demande de choisir un changement. Hors d'un terminal interactif, il quitte avec le code 1 et affiche la commande à relancer à la place.

Arguments

Argument	Description
`change-name`	Le changement à archiver, par nom de dossier (`add-rate-limit`).

Options

Option	Effet
`-y, --yes`	Répondre oui à toutes les confirmations : mises à jour des spécifications, tâches incomplètes, validation ignorée.
`--skip-specs`	Archiver sans toucher aux spécifications principales (changements d'infrastructure, d'outillage ou uniquement de documentation).
`--no-validate`	Ignorer la validation. Archive vous demande d'abord de confirmer, et `-y` y répond.
`--json`	Afficher un résultat structuré au lieu du texte. Nécessite `--yes` pour confirmer les mises à jour des spécifications.
`--store <id>`	Utiliser un store enregistré comme racine OpenSpec au lieu du projet courant.

Sortie

Une exécution réussie affiche le statut des tâches, prévisualise les mises à jour des spécifications, les applique et nomme le dossier d'archive :

Task status: ✓ Complete

Specs to update:
  api: update
Applying changes to openspec/specs/api/spec.md:
  + 1 added
Totals: + 1, ~ 0, - 0, → 0
Specs updated successfully.
Change 'add-rate-limit' archived as '2026-08-11-add-rate-limit'.

Le dossier du changement est déplacé intégralement vers openspec/changes/archive/2026-08-11-add-rate-limit/, la date du jour étant préfixée à son nom. Chaque delta est fusionné dans sa spécification principale : l'exigence ADDED ci-dessus a été ajoutée à openspec/specs/api/spec.md. Sans -y, archive affiche la prévisualisation et demande confirmation avant de mettre à jour. Refuser archive quand même le changement et laisse les spécifications intactes.

Avec --json --yes :

json

{
  "archive": {
    "change": "add-rate-limit",
    "archivedAs": "2026-08-11-add-rate-limit",
    "path": "/Users/you/projects/my-app/openspec/changes/archive/2026-08-11-add-rate-limit",
    "specsUpdated": true,
    "totals": {
      "added": 1,
      "modified": 0,
      "removed": 0,
      "renamed": 0
    }
  },
  "root": {
    "path": "/Users/you/projects/my-app",
    "source": "nearest"
  }
}

Archive valide d'abord le changement et refuse celui qui échoue :

Validation errors in change delta specs:
  ✗ ADDED "Rate limiting" must include at least one scenario

Validation failed. Please fix the errors before archiving.
To skip validation (not recommended), use --no-validate flag.

Les tâches incomplètes émettent un avertissement mais ne bloquent pas. En mode interactif, archive demande si vous souhaitez continuer, et -y continue automatiquement :

Task status: 1/2 tasks
Warning: 1 incomplete task(s) found. Continuing due to --yes flag.

Codes de sortie

0 : le changement a été archivé, avec ou sans mises à jour des spécifications.
1 : la validation a échoué, le nom du changement est inconnu, ou une confirmation était nécessaire et aucune réponse n'a pu être lue.

openspec new

Crée un nouveau répertoire de changement.

bash

openspec new change add-caching                                # metadata only
openspec new change add-search --goal "Users can search docs"  # record a goal

new a une sous-commande, new change <name>. Il crée openspec/changes/<name>/ contenant un seul fichier de métadonnées .openspec.yaml :

yaml

schema: spec-driven
created: 2026-08-11

Les artefacts (proposal, specs, design, tasks) ne sont pas créés ici. Vous les écrivez plus tard, et openspec status vous indique lequel vient ensuite.

Arguments

Argument	Description
`name`	Nom du dossier pour le changement (`add-caching`).

Options

Option	Effet
`--description <text>`	Créer également un `README.md` dans le répertoire du changement avec ce texte.
`--goal <text>`	Stocker une ligne `goal:` dans `.openspec.yaml`.
`--schema <name>`	Schéma de workflow pour le changement. Par défaut : `spec-driven`, le seul schéma fourni.
`--json`	Afficher le changement créé au format JSON au lieu du texte.
`--store <id>`	Utiliser un store enregistré comme racine OpenSpec au lieu du projet courant.

Sortie

Created change 'add-caching' at openspec/changes/add-caching/
Schema: spec-driven
Next: openspec status --change add-caching

Lorsqu'aucun répertoire openspec/ n'a été trouvé, new change en crée un à l'emplacement actuel et l'indique :

Created change 'add-caching' at openspec/changes/add-caching/
Schema: spec-driven
Next: openspec status --change add-caching

Note: no OpenSpec root was found here, so one was created at openspec/.
Run `openspec init` to finish setting this project up, or delete that directory if you meant a different project.

La note est envoyée vers stdout avec le reste de la sortie lisible, et n'apparaît jamais avec --json.

Avec --json, dans un projet ayant déjà un openspec/ :

json

{
  "change": {
    "id": "add-caching",
    "path": "/Users/you/projects/my-app/openspec/changes/add-caching",
    "metadataPath": "/Users/you/projects/my-app/openspec/changes/add-caching/.openspec.yaml",
    "schema": "spec-driven"
  },
  "root": {
    "path": "/Users/you/projects/my-app",
    "source": "nearest"
  }
}

Lorsqu'aucun répertoire openspec/ n'a été trouvé et que new change en a créé un, le JSON a la même structure. root.path est le répertoire depuis lequel vous l'avez exécuté, et root.source vaut implicit :

json

"root": {
  "path": "/Users/you/projects/my-app",
  "source": "implicit"
}

Codes de sortie

0 : changement créé.
1 : le changement existe déjà, ou le schéma est inconnu.

openspec status

Signale le statut d'avancement des artefacts pour un changement ou pour chaque changement actif.

bash

openspec status --change add-rate-limit          # vue liste de contrôle
openspec status --change add-rate-limit --json   # rapport structuré
openspec status --all                            # chaque changement actif
openspec status --all --json                     # un rapport groupé

Lorsque des changements actifs existent, utilisez exactement l'un des paramètres --change ou --all. Sans l'un ni l'autre, status se termine avec le code 1 et liste les changements disponibles, même s'il n'y en a qu'un seul :

text

✖ Error: Missing required option --change (or --all for every active change). Available changes:
  add-rate-limit

Lorsque le projet n'a aucun changement actif, status affiche No active changes. Create one with: openspec new change <name> et se termine avec le code 0 même sans l'un ni l'autre des paramètres. Avec --all --json, le même état vide est { "changes": [], "message": "No active changes.", "root": ... }.

Options

Paramètre	Effet
`--change <id>`	Le changement à rapporter, par nom de dossier.
`--all`	Rapporter chaque changement actif, trié par nom. Ne peut pas être combiné avec `--change`.
`--schema <name>`	Remplacer le schéma détecté automatiquement à partir de `openspec/config.yaml`. Un nom inconnu est une erreur.
`--json`	Afficher un rapport structuré au lieu de texte.
`--store <id>`	Utiliser un magasin enregistré comme racine OpenSpec au lieu du projet courant.

Sortie

Une liste de contrôle des artefacts du schéma : [x] terminé, [ ] prêt à écrire, [-] bloqué jusqu'à ce que les artefacts dont il dépend existent.

Change: add-rate-limit
Schema: spec-driven
Change root: /Users/you/projects/my-app/openspec/changes/add-rate-limit
Progress: 2/4 artifacts complete

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

Next: openspec instructions design --change "add-rate-limit" --json

La ligne Next: indique la commande unique qui fait avancer le changement, de sorte que openspec status suffit pour reprendre un changement dans une nouvelle session. Elle indique le prochain artefact prêt tant que la planification n'est pas terminée, et openspec instructions apply une fois que tous les artefacts de planification existent :

[x] proposal
[x] specs
[x] design
[x] tasks

All planning artifacts complete!
Next: openspec instructions apply --change "add-rate-limit" --json

Il inclut --store <id> lorsque la racine résolue est un magasin, et indique la même commande que la phrase nextSteps du JSON.

--json ajoute les dépendances par artefact, les chemins de fichiers résolus, et une prochaine étape suggérée. Version tronquée :

json

{
  "changeName": "add-rate-limit",
  "schemaName": "spec-driven",
  "isComplete": false,
  "nextSteps": [
    "Run openspec instructions design --change \"add-rate-limit\" --json before writing that artifact."
  ],
  "artifacts": [
    {
      "id": "proposal",
      "outputPath": "proposal.md",
      "status": "done",
      "requires": []
    },
    {
      "id": "design",
      "outputPath": "design.md",
      "status": "ready",
      "requires": [
        "proposal"
      ]
    },
    {
      "id": "tasks",
      "outputPath": "tasks.md",
      "status": "blocked",
      "requires": [
        "specs",
        "design"
      ],
      "missingDeps": [
        "design"
      ]
    }
  ]
}

Avec --all --json, changes contient le même objet de statut pour chaque changement, sans root par changement. La racine sélectionnée apparaît une fois sur l'enveloppe. Cet exemple tronque les champs de statut par changement affichés ci-dessus :

json

{
  "changes": [
    {
      "changeName": "add-rate-limit",
      "schemaName": "spec-driven",
      "artifacts": []
    }
  ],
  "root": {
    "path": "/Users/you/projects/my-app",
    "source": "nearest"
  }
}

Si un changement ne peut pas être chargé, le traitement groupé continue. Son entrée contient changeName et un diagnostic status tandis que les autres entrées restent disponibles. La commande se termine avec le code 1, y compris en mode JSON, afin que la CI n'accepte pas un rapport incomplet comme réussi. La sortie JSON reste un document analysable unique.

Codes de sortie

0 : chaque statut demandé a été affiché ; un rapport --all vide se termine également avec le code 0.
1 : un changement demandé n'a pas pu être chargé, --change ou --all est manquant, les deux paramètres ont été combinés, le changement n'existe pas, ou le schéma de remplacement est inconnu.

openspec instructions

Affiche les instructions pour créer un artefact, appliquer ou archiver. Votre agent exécute cette commande pendant le flux de travail pour récupérer le texte d'instruction pour son étape suivante.

bash

openspec instructions proposal --change add-rate-limit   # comment écrire un artefact
openspec instructions apply --change add-rate-limit      # comment implémenter le changement
openspec instructions archive --change add-rate-limit    # entrées pour l'archivage

Arguments

Argument	Ce que c'est
`artifact`	Un identifiant d'artefact du schéma (`proposal`, `specs`, `design`, `tasks` dans `spec-driven`), ou les mots réservés `apply` et `archive`.

Options

Paramètre	Effet
`--change <id>`	Le changement pour lequel générer les instructions. Requis.
`--schema <name>`	Remplacer le schéma. Détecté automatiquement à partir de `config.yaml` sinon.
`--json`	Afficher un objet structuré au lieu de texte.
`--store <id>`	Utiliser un magasin enregistré comme racine OpenSpec au lieu du projet courant.

Sortie

La forme artefact affiche un bloc d'instruction : la tâche, le fichier à écrire, comment l'écrire, le modèle de l'artefact, et ce que son achèvement débloque.

<artifact id="proposal" change="add-rate-limit" schema="spec-driven">

<task>
Create the proposal artifact for change "add-rate-limit".
Initial proposal document outlining the change
</task>

<output>
Write to: /Users/you/projects/my-app/openspec/changes/add-rate-limit/proposal.md
</output>

<instruction>
Create the proposal document that establishes WHY this change is needed.
...

apply affiche les fichiers de contexte, la progression des tâches, et l'instruction de travail :

## Apply: add-rate-limit
Schema: spec-driven

### Context Files
- proposal: /Users/you/projects/my-app/openspec/changes/add-rate-limit/proposal.md
- specs: /Users/you/projects/my-app/openspec/changes/add-rate-limit/specs/api/spec.md
- tasks: /Users/you/projects/my-app/openspec/changes/add-rate-limit/tasks.md

### Progress
1/3 complete

### Tasks
- [x] 1.1 Add rate limit middleware
- [ ] 1.2 Return 429 with Retry-After header
- [ ] 1.3 Add tests for burst traffic

### Instruction
Read context files, work through pending tasks, mark complete as you go.
Pause if you hit blockers or need clarification.

No project context or operation guidance configured.

Lorsque des artefacts requis sont manquants, apply signale ### ⚠️ Blocked et les nomme à la place. archive affiche le nom du changement ainsi que tout contexte de projet et guide d'opération de la configuration. S'il n'y en a aucun configuré, il l'indique et rien de plus.

Avec --json, chaque forme retourne un objet. La forme artefact commence par :

json

{
  "changeName": "add-rate-limit",
  "artifactId": "proposal",
  "schemaName": "spec-driven",
  "changeDir": "/Users/you/projects/my-app/openspec/changes/add-rate-limit",
  ...

et se poursuit avec outputPath, existingOutputPaths, les chaînes complètes instruction et template, dependencies, unlocks, et root. La forme apply porte contextFiles, progress, tasks, taskTrackingConfigured, state (blocked, ready, all_done), et instruction.

Chaque entrée tasks porte id, description, done, sourcePath, et line. sourcePath est le chemin absolu vers le fichier suivi qui a fourni la tâche. line est le numéro de ligne commençant à 1 de la case à cocher de la tâche dans ce fichier.

taskTrackingConfigured est toujours un booléen : true lorsque le schéma définit un apply.tracks non nul, même si aucun fichier ne correspond, et false sinon. Si un fichier de suivi correspondant ne peut pas être lu, unavailableTrackingFiles contient son chemin absolu path et la raison de l'erreur reason. Ce champ est omis lorsque chaque fichier correspondant est lisible. Les fichiers lisibles contribuent toujours à tasks et progress, mais state ne peut pas être all_done tant que tous les fichiers correspondants n'ont pas été lus.

Codes de sortie

0 : instructions affichées.
1 : artefact inconnu, changement inconnu, schéma inconnu, ou --change manquant. Chaque erreur liste les valeurs valides.

openspec templates

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

bash

openspec templates          # schéma par défaut : spec-driven
openspec templates --json   # map des identifiants d'artefacts vers les chemins

Options

Drapeau	Effet
`--schema <name>`	Schéma à résoudre. Par défaut : `spec-driven`.
`--json`	Affiche une map JSON des identifiants d'artefacts vers les chemins des modèles.

Sortie

Schema: spec-driven
Source: package

proposal:
  /usr/local/lib/node_modules/@fission-ai/openspec/schemas/spec-driven/templates/proposal.md
specs:
  /usr/local/lib/node_modules/@fission-ai/openspec/schemas/spec-driven/templates/spec.md
design:
  /usr/local/lib/node_modules/@fission-ai/openspec/schemas/spec-driven/templates/design.md
tasks:
  /usr/local/lib/node_modules/@fission-ai/openspec/schemas/spec-driven/templates/tasks.md

Source indique d'où provient le schéma résolu : project (openspec/schemas/ dans votre projet), user (un remplacement global), ou package (intégré au CLI). Le projet prime sur l'utilisateur, l'utilisateur sur le package.

json

{
  "proposal": {
    "path": "/usr/local/lib/node_modules/@fission-ai/openspec/schemas/spec-driven/templates/proposal.md",
    "source": "package"
  },
  "specs": {
    "path": "/usr/local/lib/node_modules/@fission-ai/openspec/schemas/spec-driven/templates/spec.md",
    "source": "package"
  },
  "design": {
    "path": "/usr/local/lib/node_modules/@fission-ai/openspec/schemas/spec-driven/templates/design.md",
    "source": "package"
  },
  "tasks": {
    "path": "/usr/local/lib/node_modules/@fission-ai/openspec/schemas/spec-driven/templates/tasks.md",
    "source": "package"
  }
}

Codes de sortie

0 : chemins affichés.
1 : schéma inconnu. L'erreur liste les schémas disponibles.

openspec schemas

Liste les schémas de workflow disponibles.

bash

openspec schemas          # noms, descriptions, ordre des artefacts
openspec schemas --json   # lisible par machine, pour utilisation par agent

Options

Drapeau	Effet
`--json`	Sortie au format JSON (pour utilisation par agent).

Sortie

Schémas disponibles :

  spec-driven
    Workflow OpenSpec par défaut - proposal → specs → design → tasks
    Artefacts : proposal → specs → design → tasks

Les schémas de votre projet sont étiquetés (project), et les remplacements globaux sont étiquetés (user override).

json

[
  {
    "name": "spec-driven",
    "description": "Default OpenSpec workflow - proposal → specs → design → tasks",
    "artifacts": [
      "proposal",
      "specs",
      "design",
      "tasks"
    ],
    "source": "package"
  }
]

Codes de sortie

0 : schémas listés.
1 : la liste des schémas n'a pas pu être lue.

openspec schema

Inspecte, duplique ou crée un schéma (expérimental). Chaque sous-commande affiche d'abord Note: Schema commands are experimental and may change. sur stderr.

bash

openspec schema which spec-driven          # where a schema resolves from
openspec schema fork spec-driven my-flow   # copy a schema into the project
openspec schema init my-schema             # create a schema from scratch

Sous-commande	Description
`which`	Affiche l'emplacement de résolution d'un schéma.
`validate`	Vérifie la structure et les modèles d'un schéma.
`fork`	Copie un schéma existant dans le projet pour le personnaliser.
`init`	Crée un nouveau schéma local au projet.

Les schémas sont résolus depuis trois emplacements. La première correspondance est prioritaire :

Source	Emplacement
`project`	`openspec/schemas/` dans le projet courant.
`user`	`~/.local/share/openspec/schemas/` (`XDG_DATA_HOME` et `%LOCALAPPDATA%` Windows respectés).
`package`	Les schémas fournis avec le CLI. `spec-driven` se trouve ici.

openspec schema which

Affiche quelle copie d'un schéma le CLI utilisera.

bash

openspec schema which spec-driven
openspec schema which --all        # every schema, grouped by source

Arguments

Argument	Description
`name`	Le schéma à rechercher. Obligatoire sauf si `--all` est défini. Sans l'un ni l'autre, la commande se termine avec le code 1.

Options

Drapeau	Effet
`--all`	Liste tous les schémas avec leur source de résolution.
`--json`	Affiche la résolution au format JSON.

Sortie

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

Lorsqu'une copie de priorité supérieure en masque une autre, une section Shadows: liste les copies masquées. Avec --json :

json

{
  "name": "my-flow",
  "source": "project",
  "path": "/Users/you/projects/my-app/openspec/schemas/my-flow",
  "shadows": []
}

Un nom inconnu provoque une sortie avec le code 1 et liste les schémas disponibles.

openspec schema validate

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

bash

openspec schema validate spec-driven   # one schema, from any source
openspec schema validate               # every project-local schema

Elle vérifie que schema.yaml existe et est analysable, que la structure correspond au format du schéma, que chaque fichier de modèle d'artefact existe dans le répertoire templates/ du schéma, et que le graphe de dépendances ne contient ni cycle ni référence inconnue, y compris dans apply.requires. Une valeur apply.tracks qui n'est pas exactement égale à une valeur generates d'un artefact affiche une ligne warning: mais ne fait pas échouer la validation, car OpenSpec ne peut alors pas déterminer à quel artefact appartient la progression de ce fichier.

Options

Drapeau	Effet
`--json`	Affiche un rapport structuré au lieu du texte.
`--verbose`	Affiche chaque étape de validation.

Sortie

✓ Schema 'spec-driven' is valid

Sans nom, chaque schéma du projet obtient une ligne sous un en-tête Validation Results:. Un schéma en échec liste ses problèmes et l'exécution se termine avec le code 1 :

✗ Schema 'my-schema' has errors:
  error: Template file 'tasks.md' not found for artifact 'tasks'

openspec schema fork

Copie un schéma existant dans le projet pour permettre sa personnalisation.

bash

openspec schema fork spec-driven my-flow

Arguments

Argument	Description
`source`	Le schéma à copier, depuis n'importe quelle source.
`name`	Nom de la copie. Kebab-case (`my-workflow`). Par défaut : `<source>-custom`.

Options

Drapeau	Effet
`--force`	Écrase un schéma de destination existant.
`--json`	Affiche le résultat au format JSON.

Sortie

✔ Forked 'spec-driven' to 'my-flow'

Source: /usr/local/lib/node_modules/@fission-ai/openspec/schemas/spec-driven (package)
Destination: /Users/you/projects/my-app/openspec/schemas/my-flow

Le fork se place dans openspec/schemas/, et le champ name: dans son schema.yaml est réécrit avec le nouveau nom :

openspec/schemas/my-flow/
├── schema.yaml
└── templates/
    ├── design.md
    ├── proposal.md
    ├── spec.md
    └── tasks.md

Une destination existante provoque une erreur sauf si vous passez --force. Un fork qui conserve le nom de la source masque l'original.

openspec schema init

Crée un nouveau schéma local au projet avec des modèles de démarrage.

bash

openspec schema init my-schema --description "Lightweight flow" --artifacts proposal,tasks

Sans --description et sans --artifacts dans un terminal interactif, init demande une description, une liste d'artefacts et si le schéma doit devenir le schéma par défaut du projet. En dehors d'un terminal, il utilise les valeurs par défaut ci-dessous.

Arguments

Argument	Description
`name`	Nom du nouveau schéma. Kebab-case (`my-workflow`).

Options

Drapeau	Effet
`--description <text>`	Description du schéma. Par défaut : `Custom workflow schema for <name>`.
`--artifacts <list>`	Identifiants d'artefacts séparés par des virgules parmi `proposal`, `specs`, `design`, `tasks`. Par défaut : les quatre.
`--default`	Écrit `schema: <name>` dans le fichier `openspec/config.yaml` ou `openspec/config.yml` existant. Crée `openspec/config.yaml` si aucun des deux n'existe. Les nouvelles modifications utiliseront ce schéma.
`--no-default`	Ignore la demande concernant le schéma par défaut.
`--force`	Écrase un schéma existant du même nom.
`--json`	Affiche le résultat au format JSON.

La création du schéma et la mise à jour de configuration --default constituent une seule opération. Si OpenSpec ne peut pas valider ou écrire la configuration, il laisse inchangés la configuration et tout schéma existant.

Sortie

✔ Created schema 'my-schema'

Schema created at: /Users/you/projects/my-app/openspec/schemas/my-schema

Artifacts: proposal, tasks

La structure sur le disque :

openspec/schemas/my-schema/
├── schema.yaml
└── templates/
    ├── proposal.md
    └── tasks.md

schema.yaml relie les artefacts sélectionnés avec leurs dépendances. Lorsque tasks est inclus, il obtient également une phase apply qui suit tasks.md. Utilisez le schéma avec openspec new --schema my-schema.

openspec store

Crée et gère des stores : des dépôts OpenSpec autonomes enregistrés sur votre machine.

bash

openspec store setup team-context --path ~/openspec/team-context   # create and register
openspec store register ~/stores/design-system                     # register an existing checkout
openspec store list                                                # see what's registered

Les enregistrements résident dans un registre propre à la machine : ~/.local/share/openspec/stores/registry.yaml, ou $XDG_DATA_HOME/openspec/stores/registry.yaml lorsque XDG_DATA_HOME est défini. Chaque sous-commande accepte --json pour afficher un rapport structuré au lieu du texte. L'exécution de openspec store avec une sous-commande manquante ou inconnue se termine avec le code 1 et liste les sous-commandes.

Sous-commande	Description
`setup [id]`	Crée un dossier de store et l'enregistre.
`register [path]`	Enregistre un dossier de store existant.
`unregister <id>`	Oublie l'enregistrement. Le dossier reste sur le disque.
`remove <id>`	Oublie l'enregistrement et supprime le dossier.
`list` (alias `ls`)	Liste les stores enregistrés.
`doctor [id]`	Vérifie l'enregistrement, les métadonnées et l'état Git des stores enregistrés.

openspec store setup

Crée un dossier de store et l'enregistre.

bash

openspec store setup team-context --path ~/openspec/team-context

Dans un terminal interactif, setup demande un nom et un emplacement manquants et confirme avant de créer quoi que ce soit. En dehors d'un terminal, un nom ou --path manquant provoque une sortie avec le code 1 et indique le drapeau à passer. Réexécuter setup pour un store déjà enregistré affiche Registry: already registered.

Setup se termine avec le code 1 et l'erreur store_setup_inside_git_repo lorsque --path se trouve dans un autre dépôt Git, car l'initialisation du store imbriquerait un dépôt dans un autre. --no-init-git ne crée aucun dépôt, ce qui permet d'ignorer cette vérification. Utilisez-le pour conserver un store dans ~/openspec/<id> lorsque votre répertoire personnel est lui-même un dépôt Git, comme un dépôt dotfiles.

Arguments

Argument	Description
`id`	Le nom du store. Il devient l'identifiant à passer à `--store`.

Options

Drapeau	Effet
`--path <path>`	Dossier où le store doit résider (`~` est développé).
`--init-git`	Initialise un dépôt Git avec un commit initial. Par défaut.
`--no-init-git`	Ignore toute action Git : pas d'initialisation, pas de commit initial.
`--remote <url>`	Source de clonage canonique enregistrée dans `store.yaml`.

Sortie

Store ready: team-context
Location: /Users/you/stores/team-context
OpenSpec root: ready
Registry: registered

Next: run normal OpenSpec commands against this store, for example:
  openspec new change <change-id> --store team-context
Share this store by committing and pushing it like any Git repo.

--json rapporte ce qui a été créé et où il a été enregistré :

json

{
  "store": {
    "id": "design-system",
    "root": "/Users/you/stores/design-system",
    "metadata_path": "/Users/you/stores/design-system/.openspec-store/store.yaml"
  },
  "registry": {
    "path": "/Users/you/.local/share/openspec/stores/registry.yaml",
    "registered": true,
    "already_registered": false
  },
  "git": {
    "is_repository": true,
    "initialized": true,
    "committed": true
  },
  "created_files": [
    "openspec/",
    "openspec/specs/",
    "openspec/changes/",
    "openspec/changes/archive/",
    "openspec/config.yaml",
    "openspec/specs/.gitkeep",
    "openspec/changes/archive/.gitkeep",
    ".openspec-store/store.yaml"
  ],
  "status": []
}

openspec store register

Enregistre un dossier de store existant, par exemple le store d'un collègue que vous avez cloné.

bash

openspec store register ~/stores/design-system

Le dossier doit contenir une racine openspec/ saine. Avec .openspec-store/store.yaml présent, register réutilise l'identifiant enregistré. Sans celui-ci, register demande confirmation avant de créer ces métadonnées. En dehors d'un terminal interactif, passez --yes à la place. Une machine peut enregistrer un seul checkout par identifiant de store. Un second chemin sous le même identifiant, ou le même chemin sous un second identifiant, provoque une sortie avec le code 1.

Arguments

Argument	Description
`path`	Le dossier de store à enregistrer (`~` est développé). Obligatoire.

Options

Drapeau	Effet
`--id <id>`	Identifiant du store. Par défaut : métadonnées ou nom du dossier.
`--yes`	Confirme la création des métadonnées d'identité du store pour une racine OpenSpec saine.

Sortie

Store registered: design-system
Location: /Users/you/stores/design-system
OpenSpec root: ready
Registry: registered

--json affiche la même structure de document que store setup --json.

openspec store unregister

Oublie l'enregistrement. Le dossier reste sur le disque.

bash

openspec store unregister design-system

Unregistered store: design-system
Files kept at: /Users/you/stores/design-system

openspec store remove

Oublie l'enregistrement et supprime le dossier.

bash

openspec store remove design-system --yes

En mode interactif, remove demande confirmation avant de supprimer. Avec --json ou en dehors d'un terminal interactif, la suppression nécessite --yes :

Error: Pass --yes to delete store files non-interactively.
Fix: openspec store remove design-system --yes

Remove se termine avec le code 1 et ne supprime rien lorsque le dossier ne contient pas de métadonnées de store correspondantes, ou lorsqu'il contient un autre store enregistré (par exemple un store fourni en tant que sous-module Git). Dans ce cas, l'erreur est store_remove_contains_registered_store : exécutez d'abord openspec store unregister <nested-id>, ou openspec store unregister <id> pour oublier le store sans supprimer les fichiers.

Options

Drapeau	Effet
`--yes`	Confirme la suppression du dossier de store local.

Sortie

Removed store: design-system
Deleted: /Users/you/stores/design-system

openspec store list

Liste les stores enregistrés. ls est un alias.

bash

openspec store list

OpenSpec stores (2)

ID              Location
design-system   /Users/you/stores/design-system
team-context    /Users/you/stores/team-context

Sans aucun enregistrement, list affiche No stores registered. ainsi que les commandes setup et register à exécuter ensuite.

openspec store doctor

Vérifie l'enregistrement, les métadonnées et l'état Git des stores enregistrés.

bash

openspec store doctor                # every registered store
openspec store doctor team-context  # one store

Sortie

Store doctor

team-context
  Location: /Users/you/stores/team-context
  OpenSpec root: ok
  Metadata: ok
  Git: repository detected (commits: yes, uncommitted changes: no, remote: none)
  Issues: none

Codes de sortie

0 : le rapport a été affiché, même lorsqu'un store signale des problèmes.
1 : le rapport n'a pas pu s'exécuter (par exemple un identifiant de store inconnu).

openspec doctor

Signale l'état de santé des relations pour la racine OpenSpec résolue.

bash

openspec doctor                       # nearest openspec/ root above your cwd
openspec doctor --store team-context  # a registered store as the root

Doctor est en lecture seule : il ne clone jamais, ne synchronise pas et ne répare pas. Il signale si la racine est saine et si chaque référence déclarée dans openspec/config.yaml se résout sur cette machine. Sans racine au-dessus de votre répertoire courant et sans --store, il quitte avec le code 1 et nomme vos stores enregistrés.

Options

Flag	Effet
`--store <id>`	Utiliser un store enregistré comme racine OpenSpec au lieu du projet courant.
`--json`	Imprimer le rapport de santé au format JSON.

Sortie

Doctor

Racine
  Emplacement : /Users/you/projects/my-app
  Racine OpenSpec : ok

Références
  - team-context: ok (/Users/you/stores/team-context)

Avec --store, la racine est le store et le rapport ajoute une ligne de store :

Utilisation de la racine OpenSpec : team-context (/Users/you/stores/team-context)
Doctor

Racine
  Emplacement : /Users/you/stores/team-context
  Racine OpenSpec : ok
  Store : team-context (métadonnées ok)

Références
  (aucune déclarée)

json

{
  "root": {
    "path": "/Users/you/projects/my-app",
    "source": "nearest",
    "healthy": true,
    "status": []
  },
  "store": null,
  "references": [
    {
      "store_id": "team-context",
      "root": "/Users/you/stores/team-context",
      "status": []
    }
  ],
  "status": []
}

Codes de sortie

0 : le rapport a été imprimé, y compris lorsqu'il liste des problèmes.
1 : aucune racine résolue (pas de openspec/ au-dessus de votre répertoire courant et pas de --store), ou un identifiant --store inconnu.

openspec context

Affiche le contexte de travail pour la racine OpenSpec résolue : la racine ainsi que chaque store référencé déclaré dans openspec/config.yaml, chacun avec une commande de récupération.

bash

openspec context                       # nearest openspec/ root above your cwd
openspec context --store team-context  # a registered store as the root
openspec context --json                # agent brief

Les références qui ne se résolvent pas sur cette machine se retrouvent dans une section Non disponible sur cette machine, chacune avec une solution.

Options

Flag	Effet
`--store <id>`	Utiliser un store enregistré comme racine OpenSpec au lieu du projet courant.
`--json`	Imprimer le brief d'agent au format JSON.
`--code-workspace <path>`	Écrire également un fichier d'espace de travail VS Code pour l'ensemble.
`--force`	Écraser un fichier `--code-workspace` existant.

Sortie

Contexte de travail pour my-app (/Users/you/projects/my-app)

Racine OpenSpec
  my-app  /Users/you/projects/my-app

Stores référencés
  team-context  /Users/you/stores/team-context
    Récupération : openspec show <spec-id> --type spec --store team-context

Avec --store, le store constitue l'ensemble complet :

Utilisation de la racine OpenSpec : team-context (/Users/you/stores/team-context)
Contexte de travail pour team-context (/Users/you/stores/team-context)

Racine OpenSpec
  team-context  /Users/you/stores/team-context

Aucune référence déclarée ; l'ensemble de travail est cette racine seule.

json

{
  "root": {
    "path": "/Users/you/projects/my-app",
    "source": "nearest",
    "role": "openspec_root"
  },
  "members": [
    {
      "role": "referenced_store",
      "id": "team-context",
      "path": "/Users/you/stores/team-context",
      "fetch": "openspec show <spec-id> --type spec --store team-context",
      "status": []
    }
  ],
  "status": []
}

Écriture d'un fichier d'espace de travail

--code-workspace écrit un fichier d'espace de travail VS Code au chemin que vous indiquez : un dossier pour la racine, un dossier ref:<id> par store référencé disponible. Les références indisponibles sont ignorées et nommées dans la ligne de résumé, Wrote /Users/you/projects/my-app/openspec.code-workspace (2 folders). Le résumé s'imprime sur stderr, donc la sortie standard --json reste un seul document JSON. Un fichier existant provoque une sortie avec le code 1 à moins que vous ne passiez --force.

json

{
  "folders": [
    {
      "name": "my-app",
      "path": "/Users/you/projects/my-app"
    },
    {
      "name": "ref:team-context",
      "path": "/Users/you/stores/team-context"
    }
  ]
}

Codes de sortie

0 : le rapport a été imprimé.
1 : aucune racine résolue (pas de openspec/ au-dessus de votre répertoire courant et pas de --store), ou l'écriture --code-workspace a été refusée.

openspec workset

Compose, conserve et ouvre des vues de travail personnelles. Un workset est une liste enregistrée et nommée de dossiers avec lesquels vous travaillez ensemble.

bash

openspec workset create checkout --member ~/projects/checkout-api --member web=~/projects/checkout-web
openspec workset list
openspec workset remove checkout --yes

Sous-commande	Rôle
`create [name]`	Composer et enregistrer une vue de travail nommée de dossiers sélectionnés.
`list`, `ls`	Afficher les worksets enregistrés avec leurs membres.
`open <name>`	Ouvrir un workset enregistré dans votre outil (fenêtre d'éditeur ou session d'agent).
`remove <name>`	Supprimer un workset enregistré (les dossiers membres ne sont jamais touchés).

Un workset est purement local :

Son état réside dans un seul dossier : ~/.local/share/openspec/worksets/ ($XDG_DATA_HOME/openspec/worksets/ lorsqu'il est défini ; %LOCALAPPDATA%\openspec\worksets\ sur Windows).
Rien n'est écrit dans les dossiers membres, et rien n'est validé ni partagé.
La suppression de ce dossier unique efface toute trace.

openspec workset create

Enregistre une vue de travail nommée de dossiers.

bash

openspec workset create checkout \
  --member ~/projects/checkout-api \
  --member web=~/projects/checkout-web

Dans un terminal interactif, create demande ce que les options n'ont pas fourni : le nom, les dossiers un par un, un outil, puis une proposition d'ouvrir le workset immédiatement. En dehors d'un terminal interactif, un nom ou un membre manquant est une erreur. Un nom déjà enregistré est toujours une erreur. Supprimez-le d'abord.

Arguments

Argument	Description
`name`	Le nom du workset. Kebab-case : lettres minuscules, chiffres, traits d'union simples. Requis en dehors d'un terminal interactif.

Options

Option	Effet
`--member <member>`	Dossier membre sous la forme `<path>` ou `<name>=<path>`, répétable. Le premier est le membre principal. Le chemin doit être un dossier existant, et le libellé prend par défaut le nom du dossier.
`--tool <id>`	Outil préféré pour ouvrir ce workset. Identifiants intégrés : `code` (VS Code), `cursor` (Cursor). `claude` et `codex` sont temporairement désactivés.
`--json`	Afficher le workset enregistré au format JSON.

Sortie

Saved workset 'checkout' (2 members) to your machine.
Open it any time with: openspec workset open checkout

openspec workset list

Affiche les worksets enregistrés avec leurs membres, triés par nom.

bash

openspec workset list   # alias : ls

Options

Option	Effet
`--json`	Afficher les worksets au format JSON.

Sortie

Un bloc par workset : le nom, son outil le cas échéant, puis une ligne name path par membre. Sans workset enregistré, list affiche No worksets saved. Create one with: openspec workset create.

checkout
  checkout-api  /Users/you/projects/checkout-api
  web           /Users/you/projects/checkout-web
checkout-tool  (opens in VS Code)
  checkout-api  /Users/you/projects/checkout-api

Avec --json :

json

{
  "worksets": [
    {
      "name": "checkout",
      "members": [
        {
          "name": "checkout-api",
          "path": "/Users/you/projects/checkout-api"
        },
        {
          "name": "web",
          "path": "/Users/you/projects/checkout-web"
        }
      ]
    }
  ],
  "status": []
}

openspec workset open

Ouvre un workset enregistré dans votre outil. Les outils éditeur (code, cursor) reçoivent un fichier .code-workspace généré. Une fenêtre s'ouvre et la commande retourne. Les outils agent CLI (claude, codex) prendraient le contrôle de ce terminal avec tous les membres attachés. Ils sont temporairement désactivés pendant que ce flux est retravaillé, donc les worksets s'ouvrent dans un IDE pour le moment.

bash

openspec workset open checkout                # outil enregistré, ou une invite
openspec workset open checkout --tool cursor  # cet outil juste pour cette fois

Arguments

Argument	Description
`name`	Le workset à ouvrir.

Options

Option	Effet
`--tool <id>`	Ouvrir avec cet outil juste pour cette fois.

Sans --tool et sans outil enregistré, open vous invite à choisir un outil installé. En dehors d'un terminal interactif, il quitte avec le code 1.

Un dossier membre qui n'existe plus est ignoré avec un avertissement. Lorsque le membre principal est manquant, le membre survivant suivant devient le principal pour cette ouverture. Lorsqu'aucun dossier membre n'existe, l'ouverture échoue.
--json est rejeté : open confie le terminal à l'outil et n'a pas de mode JSON.
Lorsque le lancement échoue, l'erreur se termine par la route manuelle : le chemin du fichier workspace et la liste des membres.

Codes de sortie

Miroir de l'outil : la commande quitte avec le code de sortie propre à l'outil, et un signal devient 128+n (130 après Ctrl-C).
1 : workset inconnu, aucun dossier membre disponible, ou aucun outil utilisable.

openspec workset remove

Supprime un workset enregistré et son fichier .code-workspace généré. Les dossiers membres ne sont jamais touchés.

bash

openspec workset remove checkout --yes

Dans un terminal interactif, remove affiche le workset et demande confirmation. Avec --json, ou en dehors d'un terminal, il exige --yes et quitte avec le code 1 sans celui-ci.

Options

Option	Effet
`--yes`	Confirmer la suppression de manière non interactive.
`--json`	Afficher la suppression au format JSON.

Sortie

Removed workset 'checkout'. Member folders were not touched.

openspec version

Rapporte la version d'OpenSpec en cours d'exécution et la manière dont cette copie a été installée.

bash

openspec version                 # version locale et détails d'installation
openspec version --json          # rapport local structuré
openspec version --check         # vérifie également le registre pour une mise à jour
openspec version --check --json  # rapport local et mise à jour structurés

Sans --check, cette commande est locale et ne contacte pas de registre. Elle fonctionne en dehors d'un projet OpenSpec. L'option existante openspec --version reste la forme la plus courte et n'affiche que le numéro de version brut.

Options

Option	Effet
`--json`	Afficher un document JSON versionné au lieu de texte.
`--check`	Vérifier le registre configuré pour une version plus récente.

Sortie

Pour une installation npm globale :

text

OpenSpec 1.13.2 (npm, global)

La portée d'installation est global, project, temporary pour un exécuteur éphémère tel que npx, source pour un checkout, ou standalone pour l'installation autonome. OpenSpec omet les détails qu'il ne peut pas identifier plutôt que de deviner.

--json conserve les détails inconnus comme des valeurs null explicites :

json

{
  "schemaVersion": 1,
  "version": "1.13.2",
  "install": {
    "location": "/opt/homebrew/lib/node_modules/@fission-ai/openspec",
    "packageManager": "npm",
    "scope": "global"
  }
}

Avec --check, une mise à jour disponible ajoute la dernière version et une commande lorsqu'OpenSpec peut identifier une commande sûre pour cette installation :

text

OpenSpec 1.13.2 (npm, global)
Update available: 1.14.0
  npm install -g @fission-ai/openspec@latest

json

{
  "schemaVersion": 1,
  "version": "1.13.2",
  "install": {
    "location": "/opt/homebrew/lib/node_modules/@fission-ai/openspec",
    "packageManager": "npm",
    "scope": "global"
  },
  "update": {
    "status": "available",
    "latest": "1.14.0",
    "command": "npm install -g @fission-ai/openspec@latest",
    "canSelfUpgrade": true
  }
}

Valeurs de statut de mise à jour :

Statut	Signification
`available`	Le registre a retourné une version plus récente et sûre que la version en cours.
`current`	La vérification s'est terminée sans trouver de version plus récente.
`disabled`	Un paramètre de confidentialité ou de vérification de mise à jour existant a bloqué l'accès au registre. `latest` est `null`.
`offline`	Le registre était indisponible ou a retourné une réponse inutilisable. `latest` est `null`.

Pour l'installation autonome, la commande de mise à jour est openspec install.

DO_NOT_TRACK, les refus de télémétrie, OPENSPEC_NO_UPDATE_CHECK, la détection CI et les substitutions de registre non-HTTPS rejetées désactivent la vérification. Les vérifications désactivées et hors ligne quittent toujours avec le code 0 car la disponibilité d'une mise à jour est informative. Cette commande ne met jamais à jour OpenSpec ; canSelfUpgrade indique uniquement si le chemin openspec update existant pouvait mettre à jour cette copie en toute sécurité.

Codes de sortie

0 : le rapport local a été affiché, y compris les vérifications de mise à jour désactivées ou hors ligne.
1 : la syntaxe de la commande était invalide, comme l'option --upgrade non prise en charge.

openspec install

Installe le openspec autonome. Exécutez-le depuis une installation npm ou Homebrew pour basculer, ou depuis l'installation autonome pour le mettre à niveau sur place.

bash

openspec install          # newest release
openspec install 1.15.0   # a specific release

Il exécute le script d'installation, qui sélectionne la version la plus récente dont tous les fichiers sont joints et le fichier correspondant à votre machine, et le vérifie par rapport au SHA256SUMS de cette version :

Depuis un gestionnaire de paquets : installe dans ~/.local/bin (Windows : %LOCALAPPDATA%\Programs\openspec) et affiche la commande qui supprime l'ancienne copie, comme npm uninstall -g @fission-ai/openspec. Il ne supprime jamais cette copie lui-même.
Depuis l'installation autonome : remplace le fichier en cours d'exécution là où il se trouve, sous son propre nom.

Ensuite, il indique quelle copie openspec exécute désormais, car une copie provenant d'un gestionnaire de paquets située plus tôt dans votre PATH continue de s'exécuter jusqu'à ce que vous la supprimiez.

Arguments

Argument	Description
`version`	Version à installer, comme `1.15.0`. Optionnel ; par défaut, la plus récente.

OPENSPEC_INSTALL_DIR et OPENSPEC_INSTALL_NAME permettent de choisir un autre dossier ou nom de fichier.

Codes de sortie

0 : installé.
1 : la version n'est pas une version publiée, ou le téléchargement ou l'installation a échoué. Votre copie actuelle est conservée telle quelle.

openspec feedback

Soumet des commentaires sur OpenSpec.

bash

openspec feedback "Validate output is hard to scan"
openspec feedback "Archive fails on Windows" --body "Steps: init, propose, archive. Error: EPERM."

L'interface en ligne de commande dépose votre message sous forme d'issue GitHub sur le dépôt Fission-AI/OpenSpec via votre CLI gh. Le titre devient Feedback: <message>. Le corps utilise les en-têtes du formulaire de bug : votre message sous What happened, votre texte --body sous Details, et une section Minimal steps to reproduce vous demandant d'ajouter les étapes, car la CLI ne peut pas les renseigner. Un pied de page ajoute la version de la CLI, la plateforme et l'horodatage. L'issue reçoit l'étiquette feedback. Si le dépôt ne définit pas cette étiquette, la CLI réessaie sans elle et le signale.

Arguments

Argument	Description
`message`	Résumé en une ligne. Devient le titre de l'issue. Obligatoire.

Options

Option	Effet
`--body <text>`	Description plus longue ajoutée au corps de l'issue.

Sortie

En cas de succès :

✓ Feedback submitted successfully!
Issue URL: https://github.com/Fission-AI/OpenSpec/issues/1234

Sans gh installé, ou avec gh non connecté, rien n'est soumis. La CLI affiche votre feedback formaté entre les marqueurs --- FORMATTED FEEDBACK ---, puis un lien qui ouvre le formulaire de rapport de bug avec le titre, ce qui s'est passé (votre message et le texte --body), la version de la CLI et l'environnement (plateforme et version de Node) pré-remplis. Vous complétez le reste du formulaire dans le navigateur. Le chemin sans connexion ajoute To auto-submit in the future: gh auth login.

Codes de sortie

0 : issue créée, ou le repli de soumission manuelle a été exécuté (pas de gh, ou gh non connecté).
1 : aucun message fourni.
Le code propre à gh : gh a échoué après l'authentification (réseau, limite de débit, issues désactivées). La CLI réaffiche d'abord votre feedback et l'URL de soumission manuelle.

openspec completion

Installe ou génère les complétions de shell.

bash

openspec completion install        # detect your shell, install, wire up config
openspec completion generate zsh   # print the script to stdout

Shells pris en charge : zsh, bash, fish, powershell. Chaque sous-commande accepte un argument de shell optionnel. Omettez-le et la CLI détecte votre shell à partir de l'environnement.

Sous-commande	Description
`generate [shell]`	Afficher le script de complétion sur stdout.
`install [shell]`	Écrire le script et configurer votre fichier de démarrage du shell.
`uninstall [shell]`	Supprimer le script et le bloc de configuration.

Installées avec Nix, les complétions sont déjà en place : le paquet flake fournit les scripts Bash, Fish et Zsh aux emplacements standard, donc install n'est pas nécessaire (Installation).

openspec completion generate

Affiche le script et n'écrit rien.

#compdef openspec

# Zsh completion script for OpenSpec CLI
# Auto-generated - do not edit manually

_openspec() {
  local context state line
  typeset -A opt_args
...

openspec completion install

Écrit le script et modifie votre configuration de shell. Les modifications de configuration se situent entre les marqueurs # OPENSPEC:START et # OPENSPEC:END. Un script existant est d'abord sauvegardé (copie .backup-<timestamp>).

Shell	Emplacement du script	Configuration modifiée
zsh	`~/.zsh/completions/_openspec`	`$ZDOTDIR/.zshrc` lorsque `ZDOTDIR` est un chemin absolu, sinon `~/.zshrc`
bash	`~/.local/share/bash-completion/completions/openspec`	`~/.bashrc`
fish	`~/.config/fish/completions/openspec.fish`	Aucune : fish le charge automatiquement.
powershell	`OpenSpecCompletion.ps1` à côté de votre profil	`$PROFILE`

Avec Oh My Zsh installé, le script se place dans $ZSH_CUSTOM/completions/_openspec à la place (par défaut ~/.oh-my-zsh/custom/completions/_openspec).

Un ZDOTDIR relatif ou préfixé par ~ est ignoré, et ~/.zshrc est modifié à la place. Exécuter l'installation à nouveau lorsque le script est déjà à jour ajoute tout de même le bloc au .zshrc que zsh lit.

Options

Option	Effet
`--verbose`	Afficher également le chemin installé, le chemin de sauvegarde éventuel, et le fichier de configuration modifié.

Sortie

✓ Completion script installed and .zshrc configured successfully

Restart your shell or run: exec zsh

openspec completion uninstall

Supprime le script et le bloc de configuration marqué. Il demande confirmation avant de modifier votre configuration (par défaut : Non).

Pour zsh, il nettoie le .zshrc que l'installation modifie, et aussi ~/.zshrc lorsqu'une installation antérieure y a laissé un bloc sous ZDOTDIR. Si un bloc ne peut pas être supprimé, la désinstallation nomme le fichier et quitte avec le code 1.

Options

Option	Effet
`-y, --yes`	Ignorer les invites de confirmation.

Sortie

✓ Completion script removed from /Users/you/.zsh/completions/_openspec. Removed OpenSpec configuration from ~/.zshrc

Codes de sortie

0 : script généré, installé ou supprimé. Une désinstallation annulée quitte également avec le code 0.
1 : shell non pris en charge ou non détecté, ou une étape d'installation ou de désinstallation a échoué.

openspec change

Forme nominale obsolète de show, list et validate. Chaque exécution avertit et renvoie vers les commandes verbe en premier, puis s'exécute quand même :

Warning: The "openspec change ..." commands are deprecated. Prefer verb-first commands (e.g., "openspec list", "openspec validate --changes").
Warning: "openspec change list" is deprecated. Use "openspec list".
add-rate-limit

Obsolète	Utiliser à la place
`openspec change show <name>`	`openspec show <name>`
`openspec change list`	`openspec list`
`openspec change validate <name>`	`openspec validate <name>` (tous les changements : `openspec validate --changes`)

Les sections verbe en premier documentent les options.

openspec spec

Forme nominale obsolète de show, list et validate. Chaque exécution avertit et renvoie vers les commandes verbe en premier, puis s'exécute quand même :

Warning: The "openspec spec ..." commands are deprecated. Prefer verb-first commands (e.g., "openspec show", "openspec validate --specs").
api

Obsolète	Utiliser à la place
`openspec spec show <id>`	`openspec show <id>`
`openspec spec list`	`openspec list --specs`
`openspec spec validate <id>`	`openspec validate <id>` (toutes les specs : `openspec validate --specs`)

Les sections verbe en premier documentent les options.

CLI ​

Commandes ​

openspec init ​

openspec update ​

openspec config ​

openspec config path ​

openspec config list ​

openspec config get ​

openspec config set ​

openspec config unset ​

openspec config reset ​

openspec config edit ​

openspec config profile ​

openspec list ​

openspec show ​

Pourquoi ​

Changements ​

openspec view ​

openspec validate ​

--report full|findings ​

Sortie texte des findings ​

Sortie JSON des findings ​

Demandes de rapport invalides ​

Filtrer un rapport complet en externe ​

openspec archive ​

openspec new ​

openspec status ​

openspec instructions ​

openspec templates ​

openspec schemas ​

openspec schema ​

openspec schema which ​

openspec schema validate ​

openspec schema fork ​

openspec schema init ​

openspec store ​

openspec store setup ​

openspec store register ​

openspec store unregister ​

openspec store remove ​

openspec store list ​

openspec store doctor ​

openspec doctor ​

openspec context ​

openspec workset ​

openspec workset create ​

openspec workset list ​

openspec workset open ​

openspec workset remove ​

openspec version ​

openspec install ​

openspec feedback ​

openspec completion ​

openspec completion generate ​

openspec completion install ​

openspec completion uninstall ​

openspec change ​

openspec spec ​

CLI

Commandes

openspec init

openspec update

openspec config

openspec config path

openspec config list

openspec config get

openspec config set

openspec config unset

openspec config reset

openspec config edit

openspec config profile

openspec list

openspec show

Pourquoi

Changements

openspec view

openspec validate

--report full|findings

Sortie texte des findings

Sortie JSON des findings

Demandes de rapport invalides

Filtrer un rapport complet en externe

openspec archive

openspec new

openspec status

openspec instructions

openspec templates

openspec schemas

openspec schema

openspec schema which

openspec schema validate

openspec schema fork

openspec schema init

openspec store

openspec store setup

openspec store register

openspec store unregister

openspec store remove

openspec store list

openspec store doctor

openspec doctor

openspec context

openspec workset

openspec workset create

openspec workset list

openspec workset open

openspec workset remove

openspec version

openspec install

openspec feedback

openspec completion

openspec completion generate

openspec completion install

openspec completion uninstall

openspec change

openspec spec