CLI

De openspec terminalcommando's.

Commando's

Instellen

Commando	Wat het doet
openspec init	Initialiseert OpenSpec in een project.
openspec update	Werk de geïnstalleerde instructiebestanden van OpenSpec bij.
openspec config	Toon en wijzig de globale configuratie.

Wijzigingen en specificaties

Commando	Wat het doet
openspec list	Lijst wijzigingen op, of specificaties met --specs.
openspec show	Druk een wijziging of specificatie af, als markdown of JSON.
openspec view	Dashboard voor één scherm met specificaties en wijzigingen.
openspec validate	Controleer wijzigingen en specificaties op structurele problemen.
openspec archive	Verplaats een voltooide wijziging naar het archief en werk de hoofdspecificaties bij.

Workflows en schema's

Je agent voert de meeste van deze commando's uit tijdens de workflow.

Commando	Wat het doet
openspec new	Maak een nieuwe wijzigingsmap aan.
openspec status	Status van voltooiing van artefacten voor één of elke actieve wijziging.
openspec instructions	Instructies voor het maken van een artefact, toepassen of archiveren.
openspec templates	Opgeloste sjabloompaden voor artefacten van een schema.
openspec schemas	Lijst beschikbare workflow-schema's op.
openspec schema	Inspecteer, fork of maak een schema (experimenteel).

Multi-repo (beta)

Commando	Wat het doet
openspec store	Maak en beheer stores: standalone OpenSpec-repo's die op je machine zijn geregistreerd.
openspec doctor	Rapporteer de gezondheidsstatus van de relaties voor de opgeloste OpenSpec-root.
openspec context	Druk de werkcontext af voor de opgeloste OpenSpec-root.
openspec workset	Stel persoonlijke werkwijzesamenstellingen samen, bewaar ze en open ze.

Hulpprogramma's

Commando	Wat het doet
openspec version	Rapporteer de geïnstalleerde versie en controleer optioneel op een update.
openspec install	Installeer de standalone openspec, die zonder Node.js draait.
openspec feedback	Dien feedback over OpenSpec in.
openspec completion	Installeer of genereer shell-aanvullingen.

Verouderd

Commando	Wat het doet
openspec change	Zelfstandig naamwoord vorm van show, list, en validate voor wijzigingen. De CLI geeft een waarschuwing en verwijst naar de commando's met werkwoord eerst.
openspec spec	Zelfstandig naamwoord vorm van show, list, en validate voor specificaties, met dezelfde waarschuwing.

Elk commando accepteert -h, --help. Het basiscommando openspec accepteert ook:

• -V, --version: druk de CLI-versie af.
• --no-color: schakel gekleurde uitvoer uit.

openspec init

Initialiseert OpenSpec in een project.

openspec init                        # huidige map, interactieve toolkiezer
openspec init --tools claude,cursor  # stel specifieke tools in, zonder interactie
openspec init --tools none           # alleen openspec/ structuur, geen toolbestanden

Als je --tools niet opgeeft, vraagt init je om tools te kiezen via een interactieve terminal. Buiten een terminal stelt het de tools in die het in het project detecteert. Als er geen tools worden gedetecteerd, slaat het af met code 1 en toont het de geldige id's.

Alleen-opslagrepositories

Als openspec/config.yaml een store:-regel bevat en het repository geen lokale specs of wijzigingen heeft, voer je init uit vanuit de repository-root:

# installeer Claude Code-integratiebestanden in de code-repository
openspec init --tools claude

• Integratiebestanden: geschreven in de code-repository.
• openspec/config.yaml: behouden byte-voor-byte.
• openspec/specs/ en openspec/changes/: worden niet aangemaakt in de code-repository.

Als je init uitvoert vanuit een submap, slaat het af met code 1 en vertelt het je om het vanuit de repository-root uit te voeren. --language slaat ook af met code 1 omdat de taal in de configuratie van de externe opslag hoort te staan. Voer init uit in de opslagroot of bewerk die configuratie rechtstreeks.

Argumenten

Argument	Wat het is
path	De projectmap die geïnitialiseerd moet worden. Standaard: huidige map. Wordt aangemaakt als het ontbreekt.

Opties

Vlag	Effect
--tools <tools>	Komma-gescheiden tool-id's, all of none. Slaat de kiezer over. Id's zijn te vinden in Ondersteunde tools.
--language <language>	Voeg een taalrichtlijn toe aan een nieuwe projectconfiguratie. Wordt afgewezen wanneer de store:-regel van het repository naar een externe opslag verwijst.
--force	Verwijder bestanden van oudere OpenSpec-indelingen zonder te vragen. Interactieve runs bevestigen de opschoning eerst.
--profile <profile>	Overschrijf het globale configuratieprofiel voor deze run: core (de standaard workflowset) of custom (de workflows die in de globale configuratie zijn opgeslagen).
--no-animation	Toon een statisch welkomstscherm in plaats van het geanimeerde scherm.

Uitvoer

Elke geselecteerde tool krijgt OpenSpec's vaardigheden en opdrachten in zijn eigen map:

▌ OpenSpec-structuur aangemaakt
✔ Setup voltooid voor Claude Code

OpenSpec Setup Complete

Aangemaakt: Claude Code
6 vaardigheden en 6 opdrachten in .claude/
Config: openspec/config.yaml (schema: spec-driven)

Aan de slag:
  Start je eerste wijziging: /opsx:propose "je idee"

Start je IDE opnieuw op om de nieuwe opdrachten te activeren.

--tools none maakt alleen openspec/config.yaml aan. In een al geïnitialiseerd project herschrijft init de geïnstalleerde bestanden op hun plaats en de samenvatting luidt Vernieuwd: Claude Code met Config: openspec/config.yaml (bestaat).

Exitcodes

• 0: setup voltooid.
• 1: ongeldige --tools- of --profile-waarde, een niet-interactieve run zonder gedetecteerde tools en zonder --tools, of een ongeldige opslag-alleen aanroep.

openspec update

Werk OpenSpec's geïnstalleerde instructiebestanden bij.

openspec update             # vernieuw tools waarvan de bestanden ouder zijn dan de CLI
openspec update --force     # herschrijf bestanden ook als ze actueel zijn
openspec update --dry-run   # toon wat een update zou veranderen, en verander niets

update zoekt de tools die init heeft geconfigureerd en vergelijkt hun gegenereerde bestanden met de versie van de CLI. Wanneer een nieuwere OpenSpec-release bestaat, wordt eerst aangeboden om de CLI te upgraden, waarna het opnieuw wordt uitgevoerd met de geüpgradede versie. Stel OPENSPEC_NO_UPDATE_CHECK=1 in om de controle over te slaan.

Argumenten

Argument	Wat het is
path	De projectmap die bijgewerkt moet worden. Standaard: huidige map.

Opties

Vlag	Effect
--force	Herschrijf de bestanden van elke geconfigureerde tool, zelfs als ze up-to-date zijn.
--dry-run	Rapporteer elk bestand dat de update zou toevoegen, wijzigen of verwijderen, en schrijf niets. Geen CLI-upgradecontrole, geen prompts. Combineer met --force om een geforceerde update te bekijken.
--json	Met --dry-run print het plan als JSON. Zonder --dry-run slaat het af met code 1.

Het bekijken van een update

--dry-run plant de update die een niet-interactieve run zou maken: hetzelfde code-pad, waarbij elke schrijf- en verwijderbewerking wordt geregistreerd in plaats van uitgevoerd. Elk bestand dat de echte update zou aanraken, wordt weergegeven, inclusief:

• het verplaatsen van OpenSpec-bestanden uit een tool's voormalige map (.kimi/ naar .kimi-code/, .windsurf/ naar .devin/, .codex/ en .agent/ naar .agents/);
• het opslaan van de globale configuratie wanneer een installatie van vóór profielen er een heeft;
• het synchroniseren van de GitHub Copilot cloud-agentbestanden;
• met --force, het instellen van tools die alleen in legacy-artifacts worden gevonden en het opruimen van die artifacts, inclusief vervallen globale Codex-prompts.

openspec update --dry-run

2 bestand(en) zouden veranderen:
  update  .claude/skills/openspec-propose/SKILL.md  (claude)
  toevoegen     ~/.config/openspec/config.json  (openspec)

--dry-run --json print hetzelfde plan als één JSON-document:

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

Veld	Wat het bevat
changes[].path	Projectrelatief pad. Een bestand buiten het project, zoals een globale vaardigheid of de globale configuratie, wordt weergegeven vanaf je thuismap als ~/..., of als een absoluut pad als het buiten de thuismap ligt.
changes[].action	add, update of delete. Een bestand waarvan de nieuwe bytes overeenkomen met de oude, wordt niet weergegeven.
changes[].tool	De geconfigureerde tool waaraan het bestand toebehoort, zoals claude. Bestanden die toebehoren aan OpenSpec zelf in plaats van aan één tool, de globale configuratie en legacy-artifact-opruiming, zijn openspec.
notes[]	{ code, message } voor een stap waarover een terminalgebruiker zou worden gevraagd. legacy-tool-directories: een verplaatsing waarover een interactieve run eerst zou vragen; changes lijst het op als gemaakt. legacy-artifacts: bestanden van OpenSpec's oudere indeling werden gevonden, zoals openspec-proposal.md slash commands of OpenSpec-markerblokken in AGENTS.md. Zonder --force laat een niet-interactieve update ze met rust, dus changes ook; --dry-run --force lijst hun opruiming op. Leeg voor een gewone vernieuwing.
failures[]	{ tool, error } voor elke tool waarop de echte update zou falen, inclusief een schrijf die het niet kan maken: een map waar een bestand thuishoort, een bestand waar een map thuishoort, of een bestand of map zonder schrijfpermissie. Voor die tool stopt changes waar de echte update stopt; de andere tools zijn nog steeds gepland. Failures die de schijf alleen tijdens het schrijven rapporteert, zoals het opraken van schijfruimte, kunnen niet worden voorspeld.

Een failure vóór het plannen, zoals geen OpenSpec-map, print nog steeds precies één JSON-document: het lege plan plus een status-array met severity, code (update_error) en message. De exitcode is 1.

Uitvoer

Wanneer de bestanden van elke tool overeenkomen met de versie van de CLI:

✓ Alle 1 tool(en) zijn up-to-date (v1.7.0)
  Tools: claude

Gebruik --force om bestanden toch te vernieuwen.

Wanneer de bestanden van een tool afkomstig zijn van een oudere CLI (of met --force, wat Force updating 1 tool(s): claude print in plaats daarvan):

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

✔ Bijgewerkt Claude Code

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

Start je IDE opnieuw op om de wijzigingen te activeren.

In een map zonder OpenSpec weigert update:

✖ Fout: Geen OpenSpec-map gevonden. Voer 'openspec init' uit eerst.

Exitcodes

• 0: bestanden bijgewerkt, of alles al up-to-date.
• 1: geen OpenSpec-map op het pad, of de update is mislukt.

openspec config

Bekijk en wijzig de globale configuratie.

openspec config list                  # zie huidige instellingen
openspec config set delivery skills   # wijzig één waarde
openspec config profile               # interactieve workflowkiezer

Subcommando	Wat het doet
path	Print de locatie van het configuratiebestand.
list	Toon alle huidige instellingen.
get <key>	Print één waarde, rauw en scriptable.
set <key> <value>	Stel een waarde in, waarbij de typecoercie wordt toegepast.
unset <key>	Verwijder een sleutel zodat de standaardwaarde van toepassing wordt.
reset	Reset alle configuratie naar standaardwaarden.
edit	Open het configuratiebestand in $EDITOR.
profile [preset]	Configureer de leveringsmodus en workflows.

Configuratie is globaal op je machine, opgeslagen als JSON waar config path naartoe wijst: $XDG_CONFIG_HOME/openspec/config.json als dat is ingesteld, anders ~/.config/openspec/config.json (macOS, Linux) of %APPDATA%\openspec\config.json (Windows). Elk subcommando accepteert --scope <scope>, maar alleen global werkt vandaag. Elke andere scope slaat af met code 1 met Fout: Project-locale configuratie is nog niet geïmplementeerd.

openspec config path

openspec config path

/Users/jij/.config/openspec/config.json

openspec config list

openspec config list          # leesbare instellingen plus profieloverzicht
openspec config list --json   # ruwe configuratie als JSON

Opties

Vlag	Effect
--json	Print het configuratieobject als JSON.

Uitvoer

Elke instelling, gevolgd door een profieloverzicht dat waarden markeert als expliciet of standaard:

featureFlags: {}
profile: core
delivery: both

Profielinstellingen:
  profile: core (standaard)
  delivery: both (standaard)
  workflows: propose, explore, apply, update, sync, archive (van core profiel)

openspec config get

openspec config get delivery

Argumenten

Argument	Wat het is
key	De sleutel om te lezen. Stippen bereiken geneste waarden (featureFlags.workspaces).

Uitvoer

De rauwe waarde, klaar voor scripts. Objecten worden afgedrukt als compacte JSON:

both

Exitcodes

• 0: waarde geprint.
• 1: sleutel heeft geen waarde, en er wordt niets geprint.

openspec config set

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

Argumenten

Argument	Wat het is
key	De sleutel om te schrijven, gestreept voor geneste waarden.
value	De nieuwe waarde. true/false worden booleaans, numerieke strings worden nummers.

Opties

Vlag	Effect
--string	Sla de waarde op als een string, waarbij typecoercie wordt overgeslagen.
--allow-unknown	Sta sleutels toe die het schema niet kent.

Uitvoer

Set featureFlags.workspaces = true

Onbekende sleutels en ongeldige waarden falen met exit 1 voordat er iets wordt opgeslagen:

Fout: Ongeldige configuratiesleutel "bogus.key". Onbekende top-level sleutel "bogus".
Gebruik "openspec config list" om beschikbare sleutels te zien.
Gebruik --allow-unknown om deze controle te omzeilen.

Fout: Ongeldige configuratie - delivery: Ongeldige optie: verwacht een van "both"|"skills"|"commands"

Als het configuratiebestand bestaat maar geen JSON-object bevat, of omdat het helemaal geen geldige JSON is of omdat de root iets anders is zoals null of een array, slaan config set, config unset en config profile af met code 1 en laten het bestand ongewijzigd. Los het op met openspec config edit, of vervang het met openspec config reset --all:

Fout: /home/jij/.config/openspec/config.json kon niet worden geparseerd, dus het werd ongewijzigd gelaten.
Los het op met "openspec config edit", of reset het met "openspec config reset --all".

Totdat het is opgelost, blijven telemetrie en de updatecontrole uitgeschakeld.

openspec config unset

openspec config unset delivery

Verwijdert de sleutel zodat de standaardwaarde opnieuw van toepassing wordt. Sleutels met ingebouwde standaardwaarden tellen altijd als ingesteld, dus dit rapporteert succes zelfs als je ze nooit hebt ingesteld:

Unset delivery (teruggezet naar standaard)

Een sleutel zonder waarde überhaupt print Sleutel "featureFlags.nothere" was niet ingesteld. Beide gevallen slaan af met code 0. Een configuratiebestand dat niet kan worden geparseerd slaat af met code 1 in plaats daarvan, zoals bij config set.

openspec config reset

openspec config reset --all      # vraagt om bevestiging
openspec config reset --all -y   # geen prompt

Opties

Vlag	Effect
--all	Vereist. Reset alles.
-y, --yes	Sla de bevestigingsprompt over.

Uitvoer

Configuratie gereset naar standaardwaarden

Zonder --all slaat het af met code 1 en print de gebruiksaanwijzing.

Exitcodes

• 0: reset voltooid, of je hebt nee geantwoord bij de prompt.
• 1: --all ontbreekt.
• 130: prompt geannuleerd met Ctrl-C.

openspec config edit

openspec config edit

Opent het configuratiebestand in $EDITOR (met een fallback naar $VISUAL), en maakt het aan met standaardwaarden als het ontbreekt. Wanneer de editor sluit, wordt het bestand gevalideerd. Ongeldige JSON of een ongeldige configuratie slaat af met code 1.

De editorwaarde mag argumenten en aangehaakte paden bevatten, zoals code --wait of "/Applications/Sublime Text.app/Contents/SharedSupport/bin/subl" -w. Het wordt opgesplitst in woorden zonder een shell, dus $VAR, ~ en ; worden letterlijk doorgegeven. Een editor die niet kan starten, of afdrukt met een niet-nulcode, print een éénregelige fout en slaat af met code 1.

Zonder een geconfigureerde editor slaat het af met code 1:

Fout: Geen editor geconfigureerd
Stel de EDITOR- of VISUAL-omgevingsvariabele in naar je voorkeureditor
Voorbeeld: export EDITOR=vim

openspec config profile

openspec config profile        # interactieve kiezer (heeft een terminal nodig)
openspec config profile core   # pas de core preset direct toe

Argumenten

Argument	Wat het is
preset	Optionele presetnaam. Alleen core bestaat. Het selecteert de core-workflows en behoudt je leveringsinstelling.

Zonder een preset toont een interactieve kiezer je huidige levering en workflows, laat je ze wijzigen (levering: beide, vaardigheden alleen, of opdrachten alleen; workflows: een checkbox-lijst), print de diff, en binnen een OpenSpec-project biedt het aan om openspec update voor je uit te voeren. Buiten een terminal slaat het af met code 1:

Interactieve modus vereist. Gebruik `openspec config profile core` of stel config via omgeving/flags in.

Uitvoer

Gewijzigde configuratie bereikt projecten niet totdat ze updaten:

Configuratie bijgewerkt. Voer `openspec update` uit in je projecten om het toe te passen.

Exitcodes

• 0: profiel opgeslagen, of je hebt de huidige instellingen behouden.
• 1: onbekende preset, geen terminal, of de aangeboden openspec update is mislukt.
• 130: kiezer geannuleerd met Ctrl-C.

openspec list

Lijst wijzigingen op, of specificaties met --specs.

openspec list                    # actieve wijzigingen, meest recent gewijzigde eerst
openspec list --archived         # gearchiveerde wijzigingen
openspec list --all              # actieve en gearchiveerde wijzigingen
openspec list --specs            # specificaties met aantal eisen
openspec list --json             # machine-leesbaar, bevat de geresolveerde root

Rijen komen uit openspec/changes/ en openspec/specs/ onder de geresolveerde root. De standaardlijst met wijzigingen slaat openspec/changes/archive/ over.

Opties

Vlag	Effect
--specs	Lijst specificaties in plaats van wijzigingen op.
--changes	Lijst wijzigingen op. Dit is de standaard.
--archived	Lijst alleen gearchiveerde wijzigingen op. Kan niet worden gecombineerd met --specs.
--all	Lijst actieve en gearchiveerde wijzigingen op. Kan niet worden gecombineerd met --specs. Heeft voorrang boven --archived.
--sort <order>	recent (laatst gewijzigd eerst) of name. Standaard: recent. Specificaties worden altijd gesorteerd op naam.
--json	Toont JSON in plaats van de tabel.
--store <id>	Gebruik een geregistreerde store als OpenSpec-root in plaats van het huidige project.

Output

Eén rij per wijziging: naam, taakstatus, laatst gewijzigd. De statuskolom leest No tasks, 2/5 tasks, of ✓ Complete.

Changes:
  add-rate-limit     No tasks      just now

--all groepeert actieve en gearchiveerde wijzigingen onder aparte koppen. Elke groep gebruikt de gekozen sorteervolgorde:

Changes:
  add-rate-limit     No tasks      just now

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

Specs:
  api     requirements 1

--json voegt taaktelningen toe en een status van no-tasks, in-progress, of complete:

{
  "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"
  }
}

Met --archived of --all bevat elk wijzigingsobject een archived boolean. De gecombineerde matrix gebruikt de gekozen sorteervolgorde. Een gearchiveerde wijziging kan nog steeds een in-progress status hebben als het bijbehorende taakbestand ongecheckte taken bevat. Zonder een van beide vlaggen blijft de JSON-vorm ongewijzigd.

Een lege lijst toont No active changes found., No archived changes found., No changes found., of No specs found. en eindigt nog steeds met exit code 0.

Een wijziging is een map direct onder openspec/changes/. In tegenstelling tot specificaties kunnen wijzigingen niet genest zijn in een namespace-map. Een map zoals changes/mobile/ die alleen een wijziging omsluit (changes/mobile/refresh-token/) wordt weergegeven met de status not a change, gevolgd door een waarschuwing die de geneste mappen noemt. --json markeert dat item met een nested matrix en voegt een top-level warnings matrix toe. show, status, validate en archive weigeren de map met hetzelfde bericht. Om dit op te lossen, verplaats de wijziging omhoog en vouw de namespace in de naam:

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

Exit codes

• 0: lijst weergegeven, ook wanneer leeg.
• 1: geen OpenSpec-root gevonden (buiten een project, geen --store).

openspec show

Toont een wijziging of specificatie, als markdown of JSON.

openspec show add-rate-limit              # wijziging: toont proposal.md
openspec show add-rate-limit --diff       # wijziging: voeg eisveranderingen toe
openspec show api                         # specificatie: toont spec.md
openspec show api --json --no-scenarios   # specatie JSON zonder scenario-tekst

Zonder naam vraagt show om wijziging of specificatie, en toont daarna een lijst met items om te kiezen uit. Buiten een interactieve terminal eindigt het met exit code 1 en toont de directe vormen in plaats daarvan.

Argumenten

Argument	Wat het is
item-name	De wijziging of specificatie om te tonen, op mappenaam (add-rate-limit, api).

Opties

Vlag	Effect
--json	Toont gestructureerde JSON in plaats van ruwe markdown.
--type <change|spec>	Kies het type wanneer een wijziging en een specificatie dezelfde naam delen.
--no-interactive	Nooit vragen: een ontbrekende naam resulteert in een fout.
--deltas-only	JSON, wijziging: beperk output tot deltas. Wijzigingen-Jason is al delta-only, dus output komt overeen met plain --json.
--requirements-only	Afgeschafde alias voor --deltas-only. Waarschuwt op stderr.
--diff	Wijziging: voeg per-eis delta-veranderingen toe. Genegeerd met een waarschuwing voor specificaties.
--requirements	JSON, specificatie: behoud eis-tekst, maak de scenarios matrices leeg.
--no-scenarios	JSON, specificatie:zelfde output als --requirements.
-r, --requirement <id>	JSON, specificatie: toon één eis op basis van 1-based positie. Kan niet worden gecombineerd met --requirements.
--store <id>	Gebruik een geregistreerde store als OpenSpec-root in plaats van het huidige project.

Vlaggen die niet van toepassing zijn op het geresolveerde type worden genegeerd met een waarschuwing op stderr.

Output

Tekstmodus is een ruwe doorgifte: een wijziging toont haar proposal.md, een specificatie toont haar spec.md.

# Add rate limiting

## Waarom
Ongeauthenticeerde clients kunnen de API overbelasten.

## Wat verandert
- Voeg per-client rate limiting toe aan de openbare API.

Bij een wijziging, drukt `--diff` eerst het voorstel af, gevolgd door een sectie `Specifications Changed (diffs)`. TOEGEVOEGDE vereisten bevatten hun volledige tekst. VERWIJDERDE vereisten behouden de opgestelde reden en migratie. HERNAAMDE vereisten tonen VAN EN NAAR. GEMODIFICEERDE vereisten tonen een unified diff ten opzichte van de bijbehorende hoofdvereiste.

Als een GEMODIFICEERDE header alleen overeenkomt na het normaliseren van hoofdletters of witruimte, bevat de output zowel de diff als een waarschuwing dat archiefmatching exact is. Als de hoofdspecificatie of vereiste ontbreekt, waarschuwt de output en drukt het volledige delta-blok af. Een GEMODIFICEERD blok zonder tekstuele verschillen drukt `(no textual changes)` af.

Een wijziging met `--json` heeft een delta-vorm:

```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"
  }
}

Elke vereiste draagt een name mee, de koptekst na Requirement:. Dit is de naam waartegen het archief GEMODIFICEERDE, VERWIJDERDE en HERNAAMDE items vergelijkt. Elk scenario draagt een name mee, de koptekst na Scenario:. Een afsluitende reeks # in beide koppen is geen deel van de naam.

--json --diff behoudt deze topniveau-vorm. Een GEMODIFICEERDE delta krijgt een diff-tekenreeks, een warning-tekenreeks, of beide. Andere bewerkingen blijven ongewijzigd. Een lege diff-tekenreeks betekent dat de hoofd- en datablokken tekstueel identiek zijn.

Een specificatie met --json lijst zijn vereisten op met scenario's. Vereisten en scenario's dragen dezelfde name-velden als de wijziging-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"
  }
}

Een onbekende naam suggereert nabije matches: Unknown item 'does-not-exist'. Did you mean: add-rate-limit, api?. Een naam die zowel aan een wijziging als aan een specificatie voldoet, geeft een fout en vraagt om --type.

Exit codes

• 0: item gedrukt.
• 1: onbekende of dubbelzinnige naam, geen naam buiten een terminal, een buiten het bereik vallende -r-index, --requirements gecombineerd met -r, of een delta of hoofdspecificatie kan niet worden gelezen voor --diff.

openspec view

Drukt een dashboard van specificaties en wijzigingen in één scherm af.

openspec view   # project samenvatting in één scherm

view drukt het dashboard een keer af en stopt. Het leest geen toetsaanslagen. Wijzigingen worden gegroepeerd op taakvoortgang: Draft (nog geen taken), Active (taken in uitvoering, met een voortgangsbalk en percentage), Completed (elke task afgewaakt). Specificaties worden opgesomd met het aantal vereisten, de grootste eerst.

Opties

Vlag	Effect
--store <id>	Gebruik een geregistreerde store als OpenSpec-root in plaats van het huidige project.

Output

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

Een Task Progress-samenvattingsregel verschijnt wanneer er een wijziging taken in uitvoering heeft.

Elke actieve wijziging toont ook de schema- en artefactstatussen onder de taakvoortgangsbalk:

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

Markering	Artefactstatus
✓	De output bestaat. Een bestaande tasks-artefact is voltooid, zelfs als de checklist onvolledig is.
→	Klaar om te maken.
Geen markering	Geblokkeerd door een ontbrekende afhankelijkheid.
(skipped)	De wijziging slaat dit over.

Als een workflow niet geladen kan worden, drukt view een waarschuwing af en houdt de taakvoortgang van die wijziging zichtbaar. Voer openspec status --change <naam> uit om de workflow afzonderlijk te inspecteren. Na openspec view --store <id>, gebruik dezelfde --store <id> voor status.

Exit codes

• 0: dashboard gedrukt.
• 1: OpenSpec-root niet gevonden (buiten een project, geen --store).

openspec validate

Controleert wijzigingen en specificaties op structurele problemen.

openspec validate add-rate-limit   # één wijziging of specificatie, per naam
openspec validate --all            # elke wijziging en specificatie

Zonder naam en zonder bulk-vlag vraagt validate je om items te selecteren. Buiten een interactieve terminal stopt het met exit code 1 en drukt de bulk-vlaggen af.

Argumenten

Argument	Wat het is
item-naam	De te valideren wijziging of specificatie, per mapnaam (add-rate-limit, api).

Opties

Vlag	Effect
--all	Valideer elke wijziging en specificatie.
--changes	Valideer elke wijziging.
--specs	Valideer elke specificatie.
--archived	Controleer taakvoltooing in gearchiveerde wijzigingen, zonder hun toegepaste specificatiedeltades te valideren.
--strict	Behandel waarschuwingen als falen.
--type <change|spec>	Kies het type wanneer een wijziging en een specificatie dezelfde naam delen.
--json	Druk een gestructureerd rapport af in plaats van tekst.
--report <mode>	Bulkoutput: full (standaard) of findings. Vereist een expliciete bulk-scope.
--concurrency <n>	Maximaal aantal parallelle validaties in bulk-uitvoeringen. Standaard: OPENSPEC_CONCURRENCY, anders 6.
--no-interactive	Vraag nooit: een ontbrekende of dubbelzinnige naam wordt een fout.
--store <id>	Gebruik een geregistreerde store als OpenSpec-root in plaats van het huidige project.

Output

Bulk-uitvoeringen drukken per item een statusregel af, gevolgd door eventuele bevindingen, en eindigen met totalen:

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

Bevindingen taakselectievakjes

Voortgang telt selectievakjes en niets anders, dus een taakbestand geschreven als eenvoudige opsommingstekens wordt gelezen als nul taken: openspec list en openspec status rapporteren geen werk, en openspec archive heeft niets om als onvolledig te markeren. Validate rapporteert een WARNING per bijgehouden taakbestand dat werk opsomt zonder selectievakje:

⚠ [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".

De waarschuwing触发 alleen als de hele bijgehouden set van de wijziging helemaal geen selectievakje bevat. Eén bestand met proza naast een echte checklist wordt niet gemeld, en een wijziging tijdens het schrijven behoudt zijn voortgang zodra er één selectievakje bestaat. --strict verandert de waarschuwing in een fout. Het regelnummer staat in het --json-rapport.

Afgebakende blokken, HTML-commentaar, YAML-frontmatter en ingesprongen code worden niet gescand, dus een geplakte terminalvoorbeeld wordt nooit verward met een takenlijst.

Bevindingen archiefmerge

Voor wijzigingen, voert validate de archiefmerge-bouwer uit ten opzichte van de huidige hoofdspecificaties zonder bestanden te schrijven. Het rapporteert merge-conflicten, zoals een ontbrekend MODIFIED-doel of een conflicterende ADDED-vereiste, als INFO:

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

Deze bevindingen verschijnen zelfs als validatie slaagt, in zowel tekst- als JSON-output. INFO verandert de exit code nooit, ook niet onder --strict: een ontbrekend doel kan bij een zusterwijziging behoren die nog niet is gearchiveerd. Deltas die al gesynchroniseerd zijn in de hoofdspecificaties volgen de bestaande merge-regels van archief.

Deze controle voert geen latere merged-spec-validatie of pensioencontroles van archief uit. Een schoon rapport garandeert niet dat archief slaagt.

Als de merge-voorcontrole niet kan starten, legt een INFO-bevinding uit waarom. Bestaande validatiebevindingen en de exit code blijven ongewijzigd.

Een falend item somt elk probleem en de oplossing op:

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 drukt één rapport af voor de uitvoering:

{
  "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"
  }
}

issues-items hebben een level van ERROR, WARNING, of INFO.

Exit codes

• 0: elk gevalideerd item slaagde, inclusief een lege bulk-scope.
• 1: een item faalde, de rapportaanvraag is ongeldig, openspec/config.yaml kan niet worden gelezen of is geen geldige YAML, of de uitvoering faalde (bijvoorbeeld een onbekende naam of geen OpenSpec-root). Een configuratie die niet kan worden gelezen of ontledstopt de uitvoering voordat er een item wordt gecontroleerd; met --json wordt dit gerapporteerd als een enkele status-item met de code unreadable_config of unparseable_config.

--report full|findings

Kiest de output voor een expliciete bulk-validatiescope:

• full: elk item. Dit is de standaard. Expliciete --report full behoudt de bestaande outputvorm zonder rapportmetadata toe te voegen.
• findings: alleen items met problemen, inclusief slaggende items met waarschuwingen of informatie. Elk item wordt nog steeds gevalideerd. Totalen, gedrag in strikte modus, en exit codes zijn ongewijzigd.

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

Scopes

Vlaggen	Bevindingen report.scope
--all	all
--changes	changes
--specs	specs
--changes --specs, of --all met een van beide vlaggen	all
--archived	archived

Beide expliciete rapportmodi wijzen een positieve itemnaam, een ontbrekende bulk-scope, of gecombineerde archief- en actieve scopes af.

Findings tekst-output

Mensenoutput: stdout drukt Scope: <scope> (<aantal> items) af, dan totalen. Zonder items met problemen:

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

Labels van items met problemen, ernstlabels, paden en berichten worden afgedrukt op stderr. Falen binnen de actieve-scope behouden de Details:-hint na de totalen. De bestaande root-banner en voortgangsoutput mogen aan het rapport voorafgaan.

Findings JSON-output

--report findings --json drukt één document af. Dit voorbeeld heeft twee schone items:

{
  "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 en report.version: identificeren de validation-findings-vorm, versie 1.0. Er is geen topniveau version of items.
• report.returnedItems en report.totalItems: tellen respectievelijk het aantal geretourneerde records en alle gevalideerde items.
• itemFindings: volledige itemrecords waarvan de issues-array niet leeg is. Bevat ERROR, WARNING, en INFO-problemen. Elk record behoudt id, type, valid, issues, en durationMs. Gearchiveerde items gebruiken type: "change".
• summary: totalen van de volledige uitvoering en aantallen per type, niet aantallen van het geretourneerde deel. Een lege scope heeft nul-totalen en stopt met exit code 0.
• root: dezelfde geselecteerde root-metadata als het volledige rapport.

Behoud van records: geretourneerde items behouden hun volledige rapportvolgorde en eventuele toegevoegde velden op items of problemen. Filtering herschrijft berichten of locaties niet, inclusief optionele line en column-velden.

Commando-fouten: fouten bij root-selectie of item-detectie behouden de bestaande status-diagnostiek en stoppen met exit code 1. Ze retourneren geen compleet bevindingen-rapport of een geslaagd leeg rapport.

Ongeldige rapportaanvragen

Beide expliciete rapportmodi wijzen deze aanvragen af vóór root-selectie of item-detectie:

• Een ondersteund rapportwaarde, inclusief een lege tekenreeks.
• Een positieve itemnaam, zelfs met een bulk-vlag.
• Geen expliciete bulk-scope.
• --archived gecombineerd met --all, --changes, of --specs.

In JSON-modus stopt een afgewezen aanvraag met exit code 1 met alleen een een-elementen status-array. Het bevat geen root of rapportpayload:

openspec validate --all --report bogus --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."
    }
  ]
}

Mensenmodus drukt de fout af op stderr. Een kaal --report zonder waarde is een Commander syntaxisfout op stderr, inclusief met --json; het gebruikt niet deze diagnostische omhulling.

Volledig rapport extern filteren

Voor een aangepaste JSON-weergave, filter het volledige rapport met jq of PowerShell. Deze scriptvoorbeelden behouden de validatie-exit code en laten commandofouten intact.

In Bash met jq:

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"

In 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

Deze aangepaste weergaven behouden de sleutels van het volledige rapport maar laten schone items weg. Ze zijn noch volledige full-v1-rapporten noch de versiegestuurde --report findings-vorm.

openspec archiveren

Verplaatst een voltooide wijziging naar de archiefmap en werkt de hoofdspecificaties bij.

openspec archive add-rate-limit -y                # archiveer één wijziging, voeg de delta's samen
openspec archive add-rate-limit -y --skip-specs   # archiveer zonder de specificaties aan te passen

Zonder opgegeven naam vraagt archive je om een wijziging te selecteren. Buiten een interactieve terminal sluit het af met exitcode 1 en geeft het in plaats daarvan de opdracht voor opnieuw uitvoeren weer.

Argumenten

Argument	Beschrijving
change-name	De te archiveren wijziging, op basis van de mapnaam (add-rate-limit).

Opties

Vlag	Effect
-y, --yes	Beantwoord 'ja' op elke bevestiging: specificatie-updates, onvolledige taken, overgeslagen validatie.
--skip-specs	Archiveer zonder de hoofdspecificaties aan te passen (infrastructuur-, tooling- of alleen-documentatiewijzigingen).
--no-validate	Sla validatie over. Archive vraagt eerst om bevestiging, en -y beantwoordt deze automatisch.
--json	Geef een gestructureerd resultaat weer in plaats van tekst. Vereist --yes om specificatie-updates te bevestigen.
--store <id>	Gebruik een geregistreerde opslag als OpenSpec-root in plaats van het huidige project.

Uitvoer

Een succesvolle uitvoering rapporteert de taakstatus, toont een voorvertoning van de specificatie-updates, past ze toe en geeft de naam van de archiefmap:

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'.

De wijzigingsmap wordt volledig verplaatst naar openspec/changes/archive/2026-08-11-add-rate-limit/, waarbij de datum van vandaag aan de naam wordt voorafgegaan. Elke delta wordt samengevoegd in de bijbehorende hoofdspecificatie: de hierboven genoemde TOEGEVOEGDE vereiste is bijvoorbeeld toegevoegd aan openspec/specs/api/spec.md. Zonder -y toont archive de voorvertoning en vraagt om bevestiging voordat updates worden toegepast. Bij weigering wordt de wijziging toch gearchiveerd en blijven de specificaties ongewijzigd.

Met --json --yes:

{
  "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 valideert de wijziging eerst en weigert deze als de validatie mislukt:

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.

Onvolledige taken geven een waarschuwing maar blokkeren niet. In interactieve modus vraagt archive of doorgewerkt moet worden, en met -y gaat het automatisch door:

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

Exitcodes

• 0: de wijziging is gearchiveerd, met of zonder specificatie-updates.
• 1: validatie mislukt, de wijzigingsnaam is onbekend, of er was een bevestiging nodig maar kon geen antwoord worden ingelezen.

openspec new

Maakt een nieuwe wijzigingsmap aan.

openspec new change add-caching                                # alleen metadata
openspec new change add-search --goal "Users can search docs"  # doel vastleggen

new heeft één subcommando: new change <name>. Het maakt openspec/changes/<name>/ aan met daarin een enkel .openspec.yaml metadatabestand:

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

Artifaten (voorstel, specificaties, ontwerp, taken) worden hier niet aangemaakt. Je schrijft ze later, en openspec status vertelt je welke als volgende aan de beurt is.

Argumenten

Argument	Beschrijving
name	Mapnaam voor de wijziging (add-caching).

Opties

Vlag	Effect
--description <text>	Maak ook een README.md in de wijzigingsmap met deze tekst.
--goal <text>	Sla een goal:-regel op in .openspec.yaml.
--schema <name>	Workflow-schema voor de wijziging. Standaard: spec-driven, het enige meegeleverde schema.
--json	Geef de aangemaakte wijziging weer als JSON in plaats van tekst.
--store <id>	Gebruik een geregistreerde opslag als OpenSpec-root in plaats van het huidige project.

Uitvoer

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

Wanneer er geen openspec/-directory werd gevonden, maakt new change er een aan op de huidige locatie en geeft dit aan:

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.

Deze mededeling wordt naar stdout gestuurd samen met de andere mens-leesbare uitvoer en verschijnt nooit bij gebruik van --json.

Met --json, in een project dat al een openspec/-directory bevat:

{
  "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"
  }
}

Wanneer er geen openspec/-directory werd gevonden en new change er een heeft aangemaakt, heeft de JSON dezelfde structuur. root.path verwijst naar de directory waarin je de opdracht hebt uitgevoerd, en root.source leest implicit:

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

Exitcodes

• 0: wijziging aangemaakt.
• 1: de wijziging bestaat al, of het schema is onbekend.

openspec status

Geeft de voltooiingsstatus van artefacten weer voor één wijziging of voor elke actieve wijziging.

openspec status --change add-rate-limit          # checklist view
openspec status --change add-rate-limit --json   # structured report
openspec status --all                            # every active change
openspec status --all --json                     # one batch report

Wanneer actieve wijzigingen bestaan, gebruik exact één van --change of --all. Zonder één van beide vangt status 1 en lijst de beschikbare wijzigingen op, zelfs als er maar één bestaat:

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

Wanneer het project geen actieve wijzigingen heeft, print status Geen actieve wijzigingen. Maak er één met: openspec new change <name> en verlaat met code 0, zelfs zonder enige vlag.

Met --all --json is dezelfde lege toestand { "changes": [], "message": "Geen actieve wijzigingen.", "root": ... }.

Opties

Vlag	Effect
--change <id>	De wijziging die moet worden gerapporteerd, op basis van de mapnaam.
--all	Rapportage van elke actieve wijziging, gesorteerd per naam. Kan niet worden gecombineerd met --change.
--schema <name>	Wijzig de automatisch gedetecteerde schema vanuit openspec/config.yaml. Een onbekende naam is een fout.
--json	Print een gestructureerde rapport in plaats van tekst.
--store <id>	Gebruik een geregistreerde store als de OpenSpec-root in plaats van het huidige project.

Uitvoer

Een checklist van de artefacten van het schema: [x] voltooid, [ ] klaar om te schrijven, [-] geblokkeerd totdat de artefacten waarop het aangewezen is, bestaan.

Wijziging: add-rate-limit
Schema: spec-driven
Wijzigingsroot: /Users/you/projects/my-app/openspec/changes/add-rate-limit
Vooruitgang: 2/4 artefacten voltooid

[x] proposal
[x] specs
[ ] design
[-] taken (gebloekt door: design)

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

Deze Next:-lijn geeft de enige opdracht die de wijziging verder brengt, dus openspec status is voldoende om een wijziging weer op te pakken in een nieuwe sessie. Het benoemt het volgende ready artifact terwijl de planning nog bezig is, en openspec instructions apply zodra alle planningartefacten zijn voltooid:

[x] proposal
[x] specs
[x] design
[x] taken

Alle planningartefacten zijn voltooid!
Volgende: openspec instructions apply --change "add-rate-limit" --json

Het draagt --store <id> wanneer de opgeloste root een store is, en noemt dezelfde opdracht als de JSON‑zin die nextSteps bevat.

Met --json retourneert elke vorm één object. De artefactvorm begint:

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

En verder met outputPath, existingOutputPaths, de volledige strings instruction en template, dependencies, unlocks, en root. De apply vorm bevat contextFiles, progress, tasks, taskTrackingConfigured, state (blocked, ready, all_done), en instruction.

Elke tasks‑invoer bevat id, beschrijving, done, sourcePath, en line. sourcePath is het absolute pad naar het bestand dat de taak leverde. line is de één‑gebaseerde lijnnummer van het vakje van de taak in dat bestand.

taskTrackingConfigured is altijd een boolean: true wanneer het schema een niet‑null apply.tracks instelt, zelfs als er geen bestand overeenkomt, en false daarentegen. Als een gematched tracking‑bestand niet kan worden gelezen, bevat unavailableTrackingFiles het absolute path en de fout reason. Dit veld wordt weggelaten wanneer alle gematchte bestanden leesbaar zijn. Leesbare bestanden dragen nog steeds bij aan tasks en progress, maar state kan niet all_done zijn totdat elke gematchte file is gelezen.

Uitgangscodes

• 0: alle gevraagde status wordt afgedrukt; een lege --all‑rapport wordt ook met code 0 beëindigd.
• 1: een gevraagde wijziging kon niet worden geladen, --change of --all ontbreekt, de twee vlaggen waren gecombineerd, de wijziging bestaat niet, of de schema‑override is onbekend.

openspec instructions

Print instructies voor het maken van een artefact, toepassen of archiveren. Jouw agent voert dit uit tijdens de workflow om de instructietekst voor de volgende stap op te halen.

openspec instructions proposal --change add-rate-limit   # hoe je één artefact maakt
openspec instructions apply --change add-rate-limit      # hoe je de wijziging implementeert
openspec instructions archive --change add-rate-limit    # invoer voor archivering

Argumenten

Argument	Wat het is
artifact	Een artefact‑id uit het schema (proposal, specs, design, tasks in spec-driven), of de gereserveerde woorden apply en archive.

Opties

Vlag	Effect
--change <id>	De wijziging waarvoor instructies worden gegenereerd. Verplicht.
--schema <name>	Wijzig het schema. Automatisch gedetecteerd vanuit config.yaml anders.
--json	Print een gestructureerd object in plaats van tekst.
--store <id>	Gebruik een geregistreerde store als de OpenSpec‑root in plaats van het huidige project.

Uitvoer

De artefactvorm print een instructie‑blok: de taak, het te schrijven bestand, hoe je het schrijft, de sjabloon van het artefact, en wat het ontgrendelt bij voltooiing.

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

<task>
Maak het proposal‑artefact voor de wijziging "add-rate-limit".
Initieel proposal‑document dat de wijziging schetst
</task>

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

<instruction>
Maak het proposal‑document dat vaststelt WAAROM deze wijziging nodig is.
...
</instruction>

apply print context bestanden, taakprogress en de werkende instructie:

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

### Context bestanden
- 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
- taken: /Users/you/projects/my-app/openspec/changes/add-rate-limit/tasks.md

### Voortgang
1/3 voltooid

### Taken
- [x] 1.1 Voeg rate‑limiet middleware toe
- [ ] 1.2 Geef 429 met Retry-After‑header terug
- [ ] 1.3 Voeg tests voor burst‑verkeer toe

### Instructie
Lees context bestanden, werk door uitgestelde taken, en markeer ze als voltooid terwijl je verdergaat.
Pauzeer als je blokkades tegenkomt of verduidelijking nodig hebt.

Geen project‑context of operationele leiding geconfigureerd.

Wanneer de vereiste artefacten ontbreken, rapporteert apply ### ⚠️ Blocked en noemt ze in plaats daarvan. archive print de wijzigingsnaam plus eventuele project‑context en operationele leiding uit de configuratie. Met geen configuratie zegt het dat en er is niets meer.

Met --json retourneert elke vorm één object. De artefactvorm begint:

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

En verder met outputPath, existingOutputPaths, de volledige strings instruction en template, dependencies, unlocks, en root. De apply vorm bevat contextFiles, progress, tasks, taskTrackingConfigured, state (blocked, ready, all_done), en instruction.

Elke tasks‑invoer bevat id, beschrijving, done, sourcePath, en line. sourcePath is het absolute pad naar het bestand dat de taak leverde. line is de één‑gebaseerde lijnnummer van het vakje van de taak in dat bestand.

taskTrackingConfigured is altijd een boolean: true wanneer het schema een niet‑null apply.tracks instelt, zelfs als er geen bestand overeenkomt, en false daarentegen. Als een gematched tracking‑bestand niet kan worden gelezen, bevat unavailableTrackingFiles het absolute path en de fout reason. Dit veld wordt weggelaten wanneer alle gematchte bestanden leesbaar zijn. Leesbare bestanden dragen nog steeds bij aan tasks en progress, maar state kan niet all_done zijn totdat elke gematchte file is gelezen.

Uitgangscodes

• 0: instructies worden afgedrukt.
• 1: onbekende artefact, onbekende wijziging, onbekende schema, of ontbrekende --change. Elk foutmelding lijst de geldige waarden.

openspec templates

Toont de vastgestelde templatepaden voor de artefacten van een schema.

openspec templates          # standaardschema: spec-driven
openspec templates --json   # toewijzing van artefact-id's naar paden

Opties

Vlag	Werking
--schema <name>	Het schema dat moet worden vastgesteld. Standaard: spec-driven.
--json	Toont een JSON-toewijzing van artefact-id's naar templatepaden.

Uitvoer

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 geeft aan waar het schema vandaan komt: project (openspec/schemas/ in je project), user (een globale override), of package (ingebouwd in de CLI). Project heeft voorrang op user, user op package.

{
  "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"
  }
}

Afsluitcodes

• 0: paden getoond.
• 1: onbekend schema. De foutmelding vermeldt de beschikbare schema's.

openspec schemas

Toont beschikbare workflowschema's.

openspec schemas          # namen, beschrijvingen, artefactvolgorde
openspec schemas --json   # machineleesbaar, voor gebruik door agents

Opties

Vlag	Werking
--json	Uitvoer als JSON (voor gebruik door agents).

Uitvoer

Available schemas:

  spec-driven
    Default OpenSpec workflow - proposal → specs → design → tasks
    Artifacts: proposal → specs → design → tasks

Schema's uit je project worden gelabeld als (project), en globale overrides worden gelabeld als (user override).

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

Afsluitcodes

• 0: schema's getoond.
• 1: de schemalijst kon niet worden gelezen.

openspec schema

Inspecteert, forkt of maakt een schema (experimenteel). Elk subcommando drukt eerst Note: Schema commands are experimental and may change. af op stderr.

openspec schema which spec-driven          # waar een schema wordt gevonden
openspec schema fork spec-driven my-flow   # kopieer een schema naar het project
openspec schema init my-schema             # maak een schema vanaf nul

Subcommando	Wat het doet
which	Toont waar een schema wordt gevonden.
validate	Controleert de structuur en sjablonen van een schema.
fork	Kopieert een bestaand schema naar het project om het aan te passen.
init	Maakt een nieuw projectspecifiek schema.

Schema's worden op drie locaties gevonden. De eerste treffer wint:

Bron	Locatie
project	openspec/schemas/ in het huidige project.
user	~/.local/share/openspec/schemas/ (XDG_DATA_HOME en Windows %LOCALAPPDATA% worden gerespecteerd).
package	De schema's die met de CLI worden meegeleverd. spec-driven staat hier.

openspec schema which

Toont welke kopie van een schema de CLI zal gebruiken.

openspec schema which spec-driven
openspec schema which --all        # elk schema, gegroepeerd per bron

Argumenten

Argument	Wat het is
name	Het schema om op te zoeken. Vereist tenzij --all is ingesteld. Zonder een van beide eindigt which met exitcode 1.

Opties

Vlag	Effect
--all	Toont elk schema met de bron waaruit het wordt gevonden.
--json	Drukt de resolutie af als JSON.

Uitvoer

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

Wanneer een kopie met hogere prioriteit een andere verbergt, somt een sectie Shadows: de verborgen kopieën op. Met --json:

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

Een onbekende naam eindigt met exitcode 1 en toont de beschikbare schema's.

openspec schema validate

Controleert de structuur en sjablonen van een schema.

openspec schema validate spec-driven   # één schema, uit elke bron
openspec schema validate               # elk projectlokaal schema

Het verifieert dat schema.yaml bestaat en kan worden geparseerd, dat de structuur overeenkomt met het schemaformaat, dat het sjabloonbestand van elk artefact bestaat binnen de map templates/ van het schema, en dat de afhankelijkheidsgraaf geen cycli of onbekende verwijzingen bevat, ook niet in apply.requires. Een waarde van apply.tracks die niet exact gelijk is aan de generates-waarde van een artefact, drukt een regel warning: af, maar laat de validatie niet mislukken, omdat OpenSpec dan niet kan bepalen bij welk artefact de voortgang van dat bestand hoort.

Opties

Vlag	Effect
--json	Drukt een gestructureerd rapport af in plaats van tekst.
--verbose	Drukt elke validatiestap af.

Uitvoer

✓ Schema 'spec-driven' is valid

Zonder naam krijgt elk projectschema één regel onder een kop Validation Results:. Een schema dat faalt, somt de problemen op en de uitvoering eindigt met exitcode 1:

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

openspec schema fork

Kopieert een bestaand schema naar het project zodat je het kunt aanpassen.

openspec schema fork spec-driven my-flow

Argumenten

Argument	Wat het is
source	Het schema om te kopiëren, uit elke bronlocatie.
name	Naam voor de kopie. Kebab-case (my-workflow). Standaard: <source>-custom.

Opties

Vlag	Effect
--force	Overschrijft een bestaand doelschema.
--json	Drukt het resultaat af als JSON.

Uitvoer

✔ 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

De fork komt terecht in openspec/schemas/, en het veld name: in schema.yaml wordt herschreven naar de nieuwe naam:

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

Een bestaande bestemming is een fout, tenzij je --force meegeeft. Een fork die de naam van de bron behoudt, overschaduwt het origineel.

openspec schema init

Maakt een nieuw projectspecifiek schema met beginsjablonen.

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

Zonder --description en zonder --artifacts in een interactieve terminal vraagt init om een beschrijving, een checklist met artefacten en of het schema de standaard van het project moet worden. Buiten een terminal worden de onderstaande standaardwaarden gebruikt.

Argumenten

Argument	Wat het is
name	Naam voor het nieuwe schema. Kebab-case (my-workflow).

Opties

Vlag	Effect
--description <text>	Schemabeschrijving. Standaard: Custom workflow schema for <name>.
--artifacts <list>	Door komma's gescheiden artefact-ID's uit proposal, specs, design, tasks. Standaard: alle vier.
--default	Schrijft schema: <name> naar het bestaande openspec/config.yaml of openspec/config.yml. Maakt openspec/config.yaml aan als geen van beide bestaat. Nieuwe wijzigingen gebruiken dit schema.
--no-default	Slaat de prompt over de standaardwaarde over.
--force	Overschrijft een bestaand schema met dezelfde naam.
--json	Drukt het resultaat af als JSON.

Het aanmaken van een schema en het bijwerken van de configuratie met --default zijn één bewerking. Als OpenSpec de configuratie niet kan valideren of schrijven, laat het zowel de configuratie als een bestaand schema ongewijzigd.

Uitvoer

✔ Created schema 'my-schema'

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

Artifacts: proposal, tasks

De indeling op schijf:

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

schema.yaml koppelt de geselecteerde artefacten aan hun afhankelijkheden. Wanneer tasks is inbegrepen, krijgt het ook een apply-fase die tasks.md bijhoudt. Gebruik het schema met openspec new --schema my-schema.

openspec store

Maakt en beheert stores: zelfstandige OpenSpec-repo's die op je machine zijn geregistreerd.

openspec store setup team-context --path ~/openspec/team-context   # maak en registreer
openspec store register ~/stores/design-system                     # registreer een bestaande checkout
openspec store list                                                # bekijk wat er is geregistreerd

Registraties staan in een register per machine: ~/.local/share/openspec/stores/registry.yaml, of $XDG_DATA_HOME/openspec/stores/registry.yaml wanneer XDG_DATA_HOME is ingesteld. Elk subcommando ondersteunt --json om een gestructureerd rapport af te drukken in plaats van tekst. Als je openspec store uitvoert met een ontbrekend of onbekend subcommando, eindigt het met exitcode 1 en worden de subcommando's getoond.

Subcommando	Wat het doet
setup [id]	Maakt een storemap aan en registreert deze.
register [path]	Registreert een bestaande storemap.
unregister <id>	Vergeet de registratie. De map blijft op schijf staan.
remove <id>	Vergeet de registratie en verwijdert de map.
list (alias ls)	Toont geregistreerde stores.
doctor [id]	Controleert registratie, metadata en Git-status voor geregistreerde stores.

openspec store setup

Maakt een storemap aan en registreert deze.

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

In een interactieve terminal vraagt setup om een ontbrekende naam en locatie en bevestigt het voordat er iets wordt aangemaakt. Buiten een interactieve terminal eindigt een ontbrekende naam of --path met exitcode 1 en wordt de mee te geven vlag getoond. Als je setup opnieuw uitvoert voor een geregistreerde store, meldt het Registry: already registered.

Setup eindigt met exitcode 1 en de fout store_setup_inside_git_repo wanneer --path zich in een andere Git-repository bevindt, omdat het initialiseren van de store daar de ene repository in de andere zou nesten. --no-init-git maakt geen repository aan en slaat die controle dus over. Gebruik dit om een store op ~/openspec/<id> te houden wanneer je thuismap zelf een Git-repository is, zoals een dotfiles-repo.

Argumenten

Argument	Wat het is
id	De storenaam. Dit wordt de id die je aan --store meegeeft.

Opties

Vlag	Effect
--path <path>	Map waar de store moet staan (~ wordt uitgebreid).
--init-git	Initialiseert een Git-repository met een eerste commit. Standaard.
--no-init-git	Slaat elke Git-actie over: geen init, geen eerste commit.
--remote <url>	Canonieke clonebron die in store.yaml wordt vastgelegd.

Uitvoer

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 rapporteert wat is aangemaakt en waar het is geregistreerd:

{
  "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

Registreert een bestaande storemap, bijvoorbeeld de store van een teamgenoot die je hebt gekloond.

openspec store register ~/stores/design-system

De map moet een gezonde openspec/-root bevatten. Als .openspec-store/store.yaml aanwezig is, hergebruikt register de vastgelegde id. Zonder dat bestand vraagt register om bevestiging voordat die metadata wordt aangemaakt. Buiten een interactieve terminal geef je in plaats daarvan --yes mee. Een machine kan één checkout per store-id registreren. Een tweede pad onder dezelfde id, of hetzelfde pad onder een tweede id, eindigt met exitcode 1.

Argumenten

Argument	Wat het is
path	De storemap om te registreren (~ wordt uitgebreid). Vereist.

Opties

Vlag	Effect
--id <id>	Store-id. Standaard: metadata of mapnaam.
--yes	Bevestigt het aanmaken van store-identiteitsmetadata voor een gezonde OpenSpec-root.

Uitvoer

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

--json drukt dezelfde documentstructuur af als store setup --json.

openspec store unregister

Vergeet de registratie. De map blijft op schijf staan.

openspec store unregister design-system

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

openspec store remove

Vergeet de registratie en verwijdert de map.

openspec store remove design-system --yes

Interactief vraagt remove om bevestiging voordat er wordt verwijderd. Met --json of buiten een interactieve terminal is --yes vereist voor verwijdering:

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

Remove eindigt met exitcode 1 en verwijdert niets wanneer de map geen overeenkomende storemetadata bevat, of wanneer deze een andere geregistreerde store bevat (bijvoorbeeld een store die als Git-submodule is opgenomen). In dat geval is de fout store_remove_contains_registered_store: voer eerst openspec store unregister <nested-id> uit, of openspec store unregister <id> om de store te vergeten zonder bestanden te verwijderen.

Opties

Vlag	Effect
--yes	Bevestigt het verwijderen van de lokale storemap.

Uitvoer

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

openspec store list

Toont geregistreerde stores. ls is een alias.

openspec store list

OpenSpec stores (2)

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

Als er niets is geregistreerd, drukt list No stores registered. af en de setup- en registercommando's die je vervolgens kunt uitvoeren.

openspec store doctor

Controleert registratie, metadata en Git-status voor geregistreerde stores.

openspec store doctor                # elke geregistreerde store
openspec store doctor team-context  # één store

Uitvoer

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

Exitcodes

• 0: het rapport is afgedrukt, zelfs wanneer een store problemen meldt.
• 1: het rapport kon niet worden uitgevoerd (bijvoorbeeld een onbekende store-id).

openspec doctor

Rapporteert de relatiestatus van de bepaalde OpenSpec-root.

openspec doctor                       # dichtstbijzijnde openspec/-root boven je cwd
openspec doctor --store team-context  # een geregistreerde store als root

Doctor is alleen-lezen: het kloont, synchroniseert of repareert nooit. Het rapporteert of de root gezond is en of elke referentie die in openspec/config.yaml is gedeclareerd, op deze machine resolveert. Als er geen root boven je cwd is en geen --store is opgegeven, wordt er afgesloten met code 1 en worden je geregistreerde stores genoemd.

Opties

Vlag	Effect
--store <id>	Gebruik een geregistreerde store als OpenSpec-root in plaats van het huidige project.
--json	Druk het statusrapport af als JSON.

Uitvoer

Doctor

Root
  Location: /Users/you/projects/my-app
  OpenSpec root: ok

References
  - team-context: ok (/Users/you/stores/team-context)

Met --store is de root de store en voegt het rapport een store-regel toe:

Using OpenSpec root: team-context (/Users/you/stores/team-context)
Doctor

Root
  Location: /Users/you/stores/team-context
  OpenSpec root: ok
  Store: team-context (metadata ok)

References
  (none declared)

{
  "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": []
}

Afsluitcodes

• 0: het rapport is afgedrukt, ook als het problemen vermeldt.
• 1: geen root bepaald (geen openspec/ boven je cwd en geen --store), of een onbekende --store-id.

openspec context

Drukt de werkcontext voor de bepaalde OpenSpec-root af: de root plus elke gerefereerde store die in openspec/config.yaml is gedeclareerd, elk met een fetch-commando.

openspec context                       # dichtstbijzijnde openspec/-root boven je cwd
openspec context --store team-context  # een geregistreerde store als root
openspec context --json                # agent brief

Referenties die op deze machine niet resolveeren, komen in een sectie Not available on this machine terecht, elk met een oplossing.

Opties

Vlag	Effect
--store <id>	Gebruik een geregistreerde store als OpenSpec-root in plaats van het huidige project.
--json	Druk de agent brief af als JSON.
--code-workspace <path>	Schrijf ook een VS Code-werkruimtebestand voor de set.
--force	Overschrijf een bestaand --code-workspace-bestand.

Uitvoer

Working context for my-app (/Users/you/projects/my-app)

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

Referenced stores
  team-context  /Users/you/stores/team-context
    Fetch: openspec show <spec-id> --type spec --store team-context

Met --store is de store de hele set:

Using OpenSpec root: team-context (/Users/you/stores/team-context)
Working context for team-context (/Users/you/stores/team-context)

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

No references declared; the working set is this root alone.

{
  "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": []
}

Een werkruimtebestand schrijven

--code-workspace schrijft een VS Code-werkruimtebestand naar het opgegeven pad: één map voor de root en één ref:<id>-map per beschikbare gerefereerde store. Niet-beschikbare referenties worden overgeslagen en genoemd in de samenvattingsregel, Wrote /Users/you/projects/my-app/openspec.code-workspace (2 folders). De samenvatting wordt afgedrukt op stderr, zodat de stdout van --json één JSON-document blijft. Een bestaand bestand sluit af met code 1, tenzij je --force doorgeeft.

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

Afsluitcodes

• 0: het rapport is afgedrukt.
• 1: geen root bepaald (geen openspec/ boven je cwd en geen --store), of het schrijven van --code-workspace werd geweigerd.

openspec workset

Stelt persoonlijke werkweergaven samen, bewaart en opent ze. Een workset is een opgeslagen, benoemde lijst met mappen waar je tegelijk in werkt.

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

Subcommando	Wat het doet
create [name]	Stel een benoemde werkweergave samen van mappen naar keuze en sla die op.
list, ls	Toon opgeslagen worksets met hun members.
open <name>	Open een opgeslagen workset in je tool (editorvenster of agentsessie).
remove <name>	Verwijder een opgeslagen workset (membermappen worden nooit aangeraakt).

Een workset is puur lokaal:

• De state staat in één map: ~/.local/share/openspec/worksets/ ($XDG_DATA_HOME/openspec/worksets/ indien ingesteld; %LOCALAPPDATA%\openspec\worksets\ op Windows).
• In de membermappen wordt niets geschreven, en er wordt niets gecommit of gedeeld.
• Door die ene map te verwijderen verdwijnt elk spoor.

openspec workset create

Slaat een benoemde werkweergave van mappen op.

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

In een interactieve terminal vraagt create om alles wat de flags niet hebben aangeleverd: de naam, de mappen één voor één, een tool, en daarna het aanbod om de workset meteen te openen. Buiten een interactieve terminal is een ontbrekende naam of member een fout. Een naam die al is opgeslagen is altijd een fout. Verwijder die eerst.

Argumenten

Argument	Wat het is
name	De naam van de workset. Kebab-case: kleine letters, cijfers, enkele koppeltekens. Verplicht buiten een interactieve terminal.

Opties

Flag	Effect
--member <member>	Membermap als <path> of <name>=<path>, herhaalbaar. De eerste is de primaire. Het pad moet een bestaande map zijn, en het label valt standaard terug op de naam van de map zelf.
--tool <id>	Voorkeurstool om deze workset mee te openen. Ingebouwde ids: code (VS Code), cursor (Cursor). claude en codex zijn tijdelijk uitgeschakeld.
--json	Print de opgeslagen workset als JSON.

Uitvoer

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

openspec workset list

Toont opgeslagen worksets met hun members, gesorteerd op naam.

openspec workset list   # alias: ls

Opties

Flag	Effect
--json	Print de worksets als JSON.

Uitvoer

Eén blok per workset: de naam, de tool als die er is, en daarna één name path-regel per member. Als er niets is opgeslagen, print list 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

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

Opent een opgeslagen workset in je tool. Editor-tools (code, cursor) krijgen een gegenereerd .code-workspace-bestand. Er opent een venster en het commando keert terug. CLI-agent-tools (claude, codex) zouden deze terminal overnemen met elke member eraan gekoppeld. Ze zijn tijdelijk uitgeschakeld terwijl die flow wordt herzien, dus worksets openen voorlopig in een IDE.

openspec workset open checkout                # opgeslagen tool, of een prompt
openspec workset open checkout --tool cursor  # deze tool, alleen deze keer

Argumenten

Argument	Wat het is
name	De workset die geopend moet worden.

Opties

Flag	Effect
--tool <id>	Open met deze tool, alleen deze keer.

Zonder --tool en zonder opgeslagen tool vraagt open je om een geïnstalleerde tool te kiezen. Buiten een interactieve terminal sluit het in plaats daarvan af met exitcode 1.

• Een membermap die niet meer bestaat, wordt overgeslagen met een waarschuwing. Als de primaire ontbreekt, wordt voor dit openen de eerstvolgende overgebleven member de primaire. Als er geen enkele membermap bestaat, mislukt het openen.
• --json wordt geweigerd: open geeft de terminal over aan de tool en heeft geen JSON-modus.
• Als het starten mislukt, eindigt de foutmelding met de handmatige route: het pad van het workspacebestand en de lijst met members.

Exitcodes

• Spiegelt de tool: het commando eindigt met de eigen exitcode van de tool, en een signaal wordt 128+n (130 na Ctrl-C).
• 1: onbekende workset, geen beschikbare membermap of geen bruikbare tool.

openspec workset remove

Verwijdert een opgeslagen workset en het gegenereerde .code-workspace-bestand. Membermappen worden nooit aangeraakt.

openspec workset remove checkout --yes

In een interactieve terminal toont remove de workset en vraagt het om bevestiging. Met --json, of buiten een terminal, is --yes vereist; zonder --yes sluit het af met exitcode 1.

Opties

Flag	Effect
--yes	Bevestig de verwijdering niet-interactief.
--json	Print de verwijdering als JSON.

Uitvoer

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

openspec version

Rapporteert de actieve OpenSpec-versie en hoe deze kopie is geïnstalleerd.

openspec version                 # lokale versie en installatiedetails
openspec version --json          # gestructureerd lokaal rapport
openspec version --check         # controleert ook de registry op een update
openspec version --check --json  # gestructureerd lokaal en updaterapport

Zonder --check is dit commando lokaal en neemt het geen contact op met een registry. Het werkt buiten een OpenSpec-project. De bestaande flag openspec --version blijft de kortste vorm en print alleen het kale versienummer.

Opties

Flag	Effect
--json	Print één JSON-document met schemaversie in plaats van tekst.
--check	Controleer de geconfigureerde registry op een nieuwere release.

Uitvoer

Bij een globale npm-installatie:

OpenSpec 1.13.2 (npm, global)

De installatiescope is global, project, temporary voor een kortstondige runner zoals npx, source voor een checkout, of standalone voor de standalone-installatie. OpenSpec laat details weg die het niet kan identificeren in plaats van te raden.

--json behoudt onbekende details als expliciete null-waarden:

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

Met --check voegt een beschikbare update de nieuwste versie en een commando toe, wanneer OpenSpec voor die installatie een veilig commando kan identificeren:

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

{
  "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
  }
}

Waarden voor de updatestatus:

Status	Betekenis
available	De registry retourneerde een veilige versie die nieuwer is dan de actieve versie.
current	De controle is voltooid en vond geen nieuwere versie.
disabled	Een bestaande privacy- of updatecontrole-instelling blokkeerde de toegang tot de registry. latest is null.
offline	De registry was onbereikbaar of retourneerde een onbruikbaar antwoord. latest is null.

Voor de standalone-installatie is het updatecommando openspec install.

DO_NOT_TRACK, opt-outs voor telemetrie, OPENSPEC_NO_UPDATE_CHECK, CI-detectie en geweigerde niet-HTTPS-registry-overschrijvingen schakelen de controle uit. Uitgeschakelde en offline controles eindigen nog steeds met exitcode 0, omdat beschikbaarheid van updates louter informatief is. Dit commando upgradet OpenSpec nooit; canSelfUpgrade geeft alleen weer of het bestaande openspec update-pad deze kopie veilig kan upgraden.

Exitcodes

• 0: het lokale rapport is afgedrukt, inclusief uitgeschakelde of offline updatecontroles.
• 1: de commandosyntaxis was ongeldig, zoals de niet-ondersteunde optie --upgrade.

openspec install

Installeert de standalone openspec. Voer het uit vanuit een npm- of Homebrew-installatie om te schakelen, of vanuit de standalone installatie om het in te upgraden.

openspec install          # nieuwste release
openspec install 1.15.0   # een specifieke release

Het voert het installatiescript uit, dat de nieuwste release kiest waarvan alle bestanden zijn bijgevoegd en het bestand voor jouw machine, en controleert dit tegen het SHA256SUMS van die release:

• Vanuit een pakketbeheer: installeert naar ~/.local/bin (Windows: %LOCALAPPDATA%\Programs\openspec) en print het commando dat de oude kopie verwijdert, zoals npm uninstall -g @fission-ai/openspec. Het verwijdert die kopie nooit zelf.
• Vanuit de standalone installatie: vervangt het lopende bestand waar het staat, onder zijn eigen naam.

Daarna geeft het aan welke kopie openspec nu draagt, aangezien een pakketbeheer-kopie eerder op je PATH blijft draaien tot je deze verwijderd.

Argumenten

Argument	Beschrijving
version	Te installeren release, zoals 1.15.0. Optioneel; standaard de laatste.

OPENSPEC_INSTALL_DIR en OPENSPEC_INSTALL_NAME kiesen een andere map of bestandsnaam.

Exit codes

• 0: geïnstalleerd.
• 1: de release is geen releaseversie, of de download of installatie is mislukt. Je huidige kopie blijft ongewijzigd.

openspec feedback

Dient feedback in over OpenSpec.

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

De CLI dient je bericht in als een GitHub-issue op de Fission-AI/OpenSpec repo via je gh CLI. De titel wordt Feedback: <bericht>. De body gebruikt de koppen van het bugformulier: je bericht onder Wat gebeurde, je --body-tekst onder Details, en een sectie Minimale stappen om te reproduceren waarin je wordt gevraagd de stappen toe te voegen, aangezien de CLI die niet kan invullen. Een footer voegt CLI-versie, platform en tijdstempel toe. Het issue krijgt het label feedback. Als de repo dat label niet definieert, probeert de CLI het opnieuw zonder het en meldt dat.

Argumenten

Argument	Beschrijving
message	Eenregels samenvatting. Wordt de issue-titel. Vereist.

Opties

Vlag	Effect
--body <text>	Langere beschrijving toegevoegd aan de issue-body.

Output

Op succes:

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

Zonder gh geïnstalleerd, of met gh niet ingelogd, niets ingediend. De CLI print je geformatteerde feedback tussen --- FORMATTED FEEDBACK --- markers, dan een link die het bugreportformulier opent met de titel, wat gebeurde (je bericht en --body-tekst), CLI-versie, en omgeving (platform en Node-versie) ingevuld. Je vult de rest van het formulier in de browser in. De niet-ingelogde pad voegt To auto-submit in the future: gh auth login toe.

Exit codes

• 0: issue gecreëerd, of de handmatige-submissiefallback liep (geen gh, of gh niet ingelogd).
• 1: geen bericht gegeven.
• gh's eigen code: gh faalde na authenticatie (netwerk, rate limit, issues uitgeschakeld). De CLI reprint je feedback en de handmatige-submissie-URL eerst.

openspec completion

Installeert of genereert shell-completions.

openspec completion install        # detecteer je shell, installeer, verbind config
openspec completion generate zsh   # print het script naar stdout

Ondersteunde shells: zsh, bash, fish, powershell. Elk subcommando neemt een optioneel shell-argument. Laat het weg en de CLI detecteert je shell uit de omgeving.

Subcommando	Wat het doet
generate [shell]	Print het completion-script naar stdout.
install [shell]	Schrijf het script en configureer je shell-startupbestand.
uninstall [shell]	Verwijder het script en het config-blok.

Geïnstalleerd met Nix, zijn de completies al op hun place: de flake-pakket levert de Bash, Fish, en Zsh scripts op de standaard locaties, dus install is niet nodig (Installation).

openspec completion generate

Drukt het script af en schrijft niets.

#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

Schrijft het script en bewerkt je shell-configuratie. Configuratiebewerkingen staan tussen # OPENSPEC:START en # OPENSPEC:END markers. Een bestaand script wordt allereerst back-up gemaakt (.backup-<timestamp> kopie).

Shell	Scriptlocatie	Gewijzigde configuratie
zsh	~/.zsh/completions/_openspec	$ZDOTDIR/.zshrc als ZDOTDIR een absoluut pad is, anders ~/.zshrc
bash	~/.local/share/bash-completion/completions/openspec	~/.bashrc
fish	~/.config/fish/completions/openspec.fish	Geen: fish laadt het automatisch in.
powershell	OpenSpecCompletion.ps1 naast je profiel	$PROFILE

Met Oh My Zsh geïnstalleerd, het script terecht in $ZSH_CUSTOM/completions/_openspec (standaard ~/.oh-my-zsh/custom/completions/_openspec).

Een relatief of ~-prefixed ZDOTDIR wordt genegeerd, en ~/.zshrc wordt bewerkt. Opnieuw uitvoeren als het script al current is, voegt nog steeds het blok toe aan de .zshrc die zsh leest.

Opties

Vlag	Effect
--verbose	Ook print het geïnstalleerde pad, eventueel back-up pad, en welk configuratiebestand is bewerkt.

Output

✓ Completion script installed and .zshrc configured successfully

Restart your shell or run: exec zsh

openspec completion uninstall

Verwijder het script en het gemarkeerde config-blok. Het vraagt voordat het je configuratie aanraakt (standaard: Nee).

Voor zsh, het schoon de .zshrc die install bewerkt, en ook ~/.zshrc wanneer een oudere installatie een blok daar onder ZDOTDIR achterliet. Als een blok niet kan worden verwijderd, noemt uninstall het bestand en exit 1.

Opties

Vlag	Effect
-y, --yes	Sla bevestigingsprompts over.

Output

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

Exit codes

• 0: script gegenereerd, geïnstalleerd, of verwijderd. Een geannuleerde uninstall ook exit 0.
• 1: shell niet ondersteund of niet gedetecteerd, of een install- of uninstall-stap is mislukt.

openspec change

Verouderde noun-vorm van show, list, en validate. Elke run waarschuft en wijst op de verb-first commando's, dan voert het uit anyway:

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

Verouderd	Gebruik in plaats daarvan
openspec change show <name>	openspec show <name>
openspec change list	openspec list
openspec change validate <name>	openspec validate <name> (all changes: openspec validate --changes)

De verb-first secties documenteren de flags.

openspec spec

Verouderde noun-vorm van show, list, en validate. Elke run waarschuft en wijst op de verb-first commando's, dan voert het uit anyway:

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

Verouderd	Gebruik in plaats daarvan
openspec spec show <id>	openspec show <id>
openspec spec list	openspec list --specs
openspec spec validate <id>	openspec validate <id> (all specs: openspec validate --specs)

De verb-first secties documenteren de flags.