CLI

I comandi da terminale di openspec.

Comandi

Configurazione

Comando	Descrizione
`openspec init`	Inizializza OpenSpec in un progetto.
`openspec update`	Aggiorna i file di istruzioni installati da OpenSpec.
`openspec config`	Visualizza e modifica la configurazione globale.

Modifiche e specifiche

Comando	Descrizione
`openspec list`	Elenca le modifiche, o le specifiche con `--specs`.
`openspec show`	Stampa una modifica o una specifica, come markdown o JSON.
`openspec view`	Dashboard in un'unica schermata di specifiche e modifiche.
`openspec validate`	Verifica la presenza di problemi strutturali nelle modifiche e nelle specifiche.
`openspec archive`	Sposta una modifica completata nell'archivio e aggiorna le specifiche principali.

Workflow e schemi

Il tuo agente esegue la maggior parte di questi comandi durante il workflow.

Comando	Descrizione
`openspec new`	Crea una nuova directory di modifica.
`openspec status`	Stato di completamento degli artifact per una singola o per tutte le modifiche attive.
`openspec instructions`	Istruzioni per la creazione di un artifact, per l'applicazione o per l'archiviazione.
`openspec templates`	Percorsi risolti dei template per gli artifact di uno schema.
`openspec schemas`	Elenca gli schemi di workflow disponibili.
`openspec schema`	Esamina, esegui il fork o crea uno schema (sperimentale).

Multi-repo (beta)

Comando	Descrizione
`openspec store`	Crea e gestisce gli store: repository OpenSpec standalone registrati sulla tua macchina.
`openspec doctor`	Segnala lo stato di salute delle relazioni per la radice OpenSpec risolta.
`openspec context`	Stampa il contesto di lavoro per la radice OpenSpec risolta.
`openspec workset`	Compone, conserva e apre viste di lavoro personali.

Utilità

Comando	Descrizione
`openspec version`	Mostra la versione installata e, facoltativamente, verifica la presenza di aggiornamenti.
`openspec install`	Installa la versione standalone di `openspec`, che funziona senza Node.js.
`openspec feedback`	Invia feedback su OpenSpec.
`openspec completion`	Installa o genera i completamenti della shell.

Deprecati

Comando	Descrizione
`openspec change`	Forma nominale di show, list e validate per le modifiche. La CLI emette un avviso e rimanda ai comandi che iniziano con il verbo.
`openspec spec`	Forma nominale di show, list e validate per le specifiche, con lo stesso avviso.

Ogni comando accetta -h, --help. Il semplice comando openspec accetta inoltre:

-V, --version: stampa la versione della CLI.
--no-color: disabilita l'output a colori.

openspec init

Inizializza OpenSpec in un progetto.

bash

openspec init                        # directory corrente, selettore interattivo degli strumenti
openspec init --tools claude,cursor  # configura strumenti specifici, nessun prompt
openspec init --tools none           # solo struttura openspec/, nessun file degli strumenti

Senza --tools, init ti chiede di scegliere gli strumenti in un terminale interattivo. Al di fuori di un terminale, configura gli strumenti che rileva nel progetto. Se non ne rileva nessuno, esce con codice 1 ed elenca gli ID validi.

Repository con solo store

Quando openspec/config.yaml contiene una riga store: e il repository non ha specifiche o modifiche locali, esegui init dalla radice del repository:

bash

# installa i file di integrazione di Claude Code nel repository del codice
openspec init --tools claude

File di integrazione: scritti nel repository del codice.
openspec/config.yaml: preservato byte per byte.
openspec/specs/ e openspec/changes/: non creati nel repository del codice.

Eseguire init da una sottodirectory esce con codice 1 e indica di eseguirlo dalla radice del repository. Anche --language esce con codice 1 perché la lingua appartiene alla configurazione dello store esterno. Esegui init nella radice dello store o modifica direttamente quella configurazione.

Argomenti

Argomento	Descrizione
`path`	La directory del progetto da inizializzare. Predefinita: directory corrente. Creata se non esiste.

Opzioni

Flag	Effetto
`--tools <tools>`	ID degli strumenti separati da virgola, `all` o `none`. Salta il selettore. Gli ID sono elencati in Strumenti supportati.
`--language <language>`	Aggiunge un'istruzione di lingua a una nuova configurazione del progetto. Rifiutato quando la riga `store:` del repository punta a uno store esterno.
`--force`	Rimuove i file dei layout OpenSpec precedenti senza chiedere. In caso contrario, le esecuzioni interattive confermano prima la pulizia.
`--profile <profile>`	Sovrascrive il profilo della configurazione globale per questa esecuzione: `core` (il set di workflow standard) o `custom` (i workflow salvati nella configurazione globale).
`--no-animation`	Mostra una schermata di benvenuto statica anziché quella animata.

Output

Ogni strumento selezionato riceve le skill e i comandi di OpenSpec nella propria directory:

▌ 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 crea solo openspec/config.yaml. Su un progetto già inizializzato, init riscrive i file installati sul posto e il riepilogo mostra Refreshed: Claude Code con Config: openspec/config.yaml (exists).

Codici di uscita

0: configurazione completata.
1: valore non valido per --tools o --profile, esecuzione non interattiva senza strumenti rilevati e senza --tools, oppure invocazione non valida in modalità solo store.

openspec update

Aggiorna i file di istruzioni installati da OpenSpec.

bash

openspec update             # aggiorna gli strumenti i cui file sono più vecchi della CLI
openspec update --force     # riscrive i file anche quando sono aggiornati
openspec update --dry-run   # elenca cosa cambierebbe un aggiornamento, senza cambiare nulla

update trova gli strumenti configurati da init e confronta i file generati con la versione della CLI. Quando esiste una release più recente di OpenSpec, propone prima di aggiornare la CLI, poi viene rieseguito con la versione aggiornata. Imposta OPENSPEC_NO_UPDATE_CHECK=1 per saltare il controllo.

Argomenti

Argomento	Descrizione
`path`	La directory del progetto da aggiornare. Predefinita: directory corrente.

Opzioni

Flag	Effetto
`--force`	Riscrive i file di ogni strumento configurato anche quando sono aggiornati.
`--dry-run`	Segnala ogni file che l'aggiornamento aggiungerebbe, cambierebbe o eliminerebbe, senza scrivere nulla. Nessun controllo di aggiornamento della CLI, nessun prompt. Combinalo con `--force` per visualizzare in anteprima un aggiornamento forzato.
`--json`	Con `--dry-run`, stampa il piano come JSON. Senza `--dry-run`, esce con codice 1.

Visualizzare in anteprima un aggiornamento

--dry-run pianifica l'aggiornamento che farebbe un'esecuzione non interattiva: lo stesso percorso di codice, con ogni scrittura ed eliminazione registrata invece che eseguita. Viene elencato ogni file che l'aggiornamento reale toccherebbe, inclusi:

lo spostamento dei file OpenSpec dalla vecchia directory di uno strumento (.kimi/ in .kimi-code/, .windsurf/ in .devin/, .codex/ e .agent/ in .agents/);
il salvataggio della configurazione globale quando un'installazione precedente all'introduzione dei profili ne riceve una;
la sincronizzazione dei file dell'agente cloud di GitHub Copilot;
con --force, la configurazione degli strumenti trovati solo in artefatti legacy e la pulizia di tali artefatti, inclusi i prompt globali di Codex ritirati.

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 stampa lo stesso piano come un unico documento JSON:

json

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

Campo	Contenuto
`changes[].path`	Percorso relativo al progetto. Un file esterno al progetto, come una skill globale o la configurazione globale, viene mostrato dalla directory home come `~/...`, oppure come percorso assoluto quando è esterno anche alla home.
`changes[].action`	`add`, `update` o `delete`. Un file i cui nuovi byte corrispondono a quelli vecchi non viene elencato.
`changes[].tool`	Lo strumento configurato a cui appartiene il file, come `claude`. I file che appartengono a OpenSpec stesso anziché a un singolo strumento, ovvero la configurazione globale e la pulizia degli artefatti legacy, sono `openspec`.
`notes[]`	`{ code, message }` per un passaggio su cui verrebbe chiesto conferma a un utente del terminale. `legacy-tool-directories`: uno spostamento su cui un'esecuzione interattiva chiede prima conferma; `changes` lo elenca come eseguito. `legacy-artifacts`: sono stati trovati file del layout precedente di OpenSpec, come comandi slash `openspec-proposal.md` o blocchi marcatore OpenSpec in `AGENTS.md`. Senza `--force`, un aggiornamento non interattivo li lascia invariati, quindi anche `changes` fa lo stesso; `--dry-run --force` elenca la loro pulizia. Vuoto per un aggiornamento ordinario.
`failures[]`	`{ tool, error }` per ogni strumento su cui l'aggiornamento reale fallirebbe, inclusa una scrittura che non può essere eseguita: una directory dove dovrebbe esserci un file, un file dove dovrebbe esserci una directory, oppure un file o una cartella senza permesso di scrittura. Per quello strumento, `changes` si ferma dove si ferma l'aggiornamento reale; gli altri strumenti vengono comunque pianificati. Gli errori che il disco segnala solo durante la scrittura, come l'esaurimento dello spazio, non possono essere previsti.

Un errore prima della pianificazione, come l'assenza della directory OpenSpec, stampa comunque esattamente un documento JSON: il piano vuoto più un array status con severity, code (update_error) e message. Il codice di uscita è 1.

Output

Quando i file di ogni strumento corrispondono alla versione della CLI:

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

Use --force to refresh files anyway.

Quando i file di uno strumento provengono da una CLI precedente (oppure con --force, che stampa al suo posto Force updating 1 tool(s): claude):

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.

In una directory senza OpenSpec, update rifiuta:

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

Codici di uscita

0: file aggiornati, oppure tutto già aggiornato.
1: nessuna directory OpenSpec nel percorso, oppure l'aggiornamento non è riuscito.

openspec config

Visualizza e modifica la configurazione globale.

bash

openspec config list                  # visualizza le impostazioni correnti
openspec config set delivery skills   # cambia un valore
openspec config profile               # selettore interattivo dei workflow

Sottocomando	Cosa fa
`path`	Stampa la posizione del file di configurazione.
`list`	Mostra tutte le impostazioni correnti.
`get <key>`	Stampa un valore, in forma grezza e utilizzabile negli script.
`set <key> <value>`	Imposta un valore, convertendone il tipo.
`unset <key>`	Rimuove una chiave in modo che si applichi il valore predefinito.
`reset`	Reimposta tutta la configurazione ai valori predefiniti.
`edit`	Apre il file di configurazione in `$EDITOR`.
`profile [preset]`	Configura la modalità di distribuzione e i workflow.

La configurazione è globale per la tua macchina, salvata come JSON nel percorso indicato da config path: $XDG_CONFIG_HOME/openspec/config.json se la variabile è impostata, altrimenti ~/.config/openspec/config.json (macOS, Linux) o %APPDATA%\openspec\config.json (Windows). Ogni sottocomando accetta --scope <scope>, ma oggi funziona solo global. Qualsiasi altro scope esce con codice 1 e 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          # impostazioni leggibili più riepilogo del profilo
openspec config list --json   # configurazione grezza come JSON

Opzioni

Flag	Effetto
`--json`	Stampa l'oggetto di configurazione come JSON.

Output

Ogni impostazione, poi un riepilogo del profilo che contrassegna i valori come espliciti o predefiniti:

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

Argomenti

Argomento	Descrizione
`key`	La chiave da leggere. I punti raggiungono valori annidati (`featureFlags.workspaces`).

Output

Il valore grezzo, pronto per gli script. Gli oggetti vengono stampati come JSON compatto:

both

Codici di uscita

0: valore stampato.
1: la chiave non ha valore e non viene stampato nulla.

openspec config set

bash

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

Argomenti

Argomento	Descrizione
`key`	La chiave da scrivere, con notazione a punti per i valori annidati.
`value`	Il nuovo valore. `true`/`false` diventano booleani, le stringhe numeriche diventano numeri.

Opzioni

Flag	Effetto
`--string`	Memorizza il valore come stringa, saltando la conversione del tipo.
`--allow-unknown`	Consente chiavi che lo schema non conosce.

Output

Set featureFlags.workspaces = true

Le chiavi sconosciute e i valori non validi falliscono con codice di uscita 1 prima che qualsiasi cosa venga salvata:

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"

Se il file di configurazione esiste ma non contiene un oggetto JSON, sia perché non è affatto JSON valido sia perché la sua radice è qualcos'altro come null o un array, config set, config unset e config profile escono con codice 1 e lasciano il file invariato. Correggilo con openspec config edit, oppure sostituiscilo con 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".

Finché non viene corretto, la telemetria e il controllo degli aggiornamenti restano disattivati.

openspec config unset

bash

openspec config unset delivery

Rimuove la chiave in modo che torni ad applicarsi il valore predefinito. Le chiavi con valori predefiniti integrati contano sempre come impostate, quindi il comando segnala successo anche se non le hai mai impostate:

Unset delivery (reverted to default)

Una chiave senza alcun valore stampa Key "featureFlags.nothere" was not set. Entrambi i casi escono con codice 0. Un file di configurazione che non può essere analizzato esce invece con codice 1, come per config set.

openspec config reset

bash

openspec config reset --all      # chiede conferma
openspec config reset --all -y   # nessun prompt

Opzioni

Flag	Effetto
`--all`	Obbligatorio. Reimposta tutto.
`-y, --yes`	Salta la richiesta di conferma.

Output

Configuration reset to defaults

Senza --all esce con codice 1 e stampa la riga di utilizzo.

Codici di uscita

0: reimpostazione eseguita, oppure hai risposto no al prompt.
1: --all mancante.
130: prompt annullato con Ctrl-C.

openspec config edit

bash

openspec config edit

Apre il file di configurazione in $EDITOR (con fallback su $VISUAL), creandolo prima con i valori predefiniti se manca. Alla chiusura dell'editor, il file viene validato. Un JSON non valido o una configurazione non valida escono con codice 1.

Il valore dell'editor può contenere argomenti e percorsi tra virgolette, ad esempio code --wait o "/Applications/Sublime Text.app/Contents/SharedSupport/bin/subl" -w. Viene suddiviso in parole senza una shell, quindi $VAR, ~ e ; vengono passati letteralmente. Un editor che non può avviarsi, o che esce con codice diverso da zero, stampa un errore su una riga ed esce con codice 1.

Senza alcun editor configurato esce con codice 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        # selettore interattivo (richiede un terminale)
openspec config profile core   # applica direttamente il preset core

Argomenti

Argomento	Descrizione
`preset`	Nome del preset facoltativo. Esiste solo `core`. Seleziona i workflow core e mantiene l'impostazione di distribuzione.

Senza preset, un selettore interattivo mostra la distribuzione e i workflow correnti, consente di modificare la distribuzione, i workflow o entrambi (distribuzione: both, solo skills o solo commands; workflow: un elenco con caselle di controllo), stampa il diff e, all'interno di un progetto OpenSpec, propone di eseguire openspec update per te. Al di fuori di un terminale esce con codice 1:

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

Output

La configurazione modificata non raggiunge i progetti finché questi non si aggiornano:

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

Codici di uscita

0: profilo salvato, oppure hai mantenuto le impostazioni correnti.
1: preset sconosciuto, nessun terminale, oppure il comando openspec update proposto non è riuscito.
130: selettore annullato con Ctrl-C.

openspec list

Elenca le modifiche, o le specifiche con --specs.

bash

openspec list                    # modifiche attive, le più recentemente modificate per prime
openspec list --archived         # modifiche archiviate
openspec list --all              # modifiche attive e archiviate
openspec list --specs            # specifiche con conteggio dei requisiti
openspec list --json             # leggibile da macchina, include la root risolta

Le righe provengono da openspec/changes/ e openspec/specs/ sotto la root risolta. L'elenco predefinito delle modifiche salta openspec/changes/archive/.

Opzioni

Flag	Effetto
`--specs`	Elenca le specifiche invece delle modifiche.
`--changes`	Elenca le modifiche. Questa è l'impostazione predefinita.
`--archived`	Elenca solo le modifiche archiviate. Non può essere combinato con `--specs`.
`--all`	Elenca le modifiche attive e archiviate. Non può essere combinato con `--specs`. Ha la precedenza su `--archived`.
`--sort <order>`	`recent` (ultima modifica per primo) o `name`. Predefinito: `recent`. Le specifiche vengono sempre ordinate per nome.
`--json`	Stampa JSON invece della tabella.
`--store <id>`	Usa un archivio registrato come root OpenSpec invece del progetto corrente.

Output

Una riga per modifica: nome, stato delle attività, ultima modifica. La colonna dello stato recita No tasks, 2/5 tasks, o ✓ Complete.

Changes:
  add-rate-limit     No tasks      just now

--all raggruppa le modifiche attive e archiviate sotto intestazioni separate. Ogni gruppo usa l'ordine di selezione scelto:

Changes:
  add-rate-limit     No tasks      just now

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

Specs:
  api     requirements 1

--json aggiunge i conteggi delle attività e uno status di no-tasks, in-progress, o 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"
  }
}

Con --archived o --all, ogni oggetto di modifica include un booleano archived. L'array combinato usa l'ordine di selezione scelto. Una modifica archiviata può comunque avere uno stato in-progress quando il suo file di attività tracciato ha attività non selezionate. Senza nessuno dei due flag, la forma JSON rimane invariata.

Un elenco vuoto stampa No active changes found., No archived changes found., No changes found., o No specs found. e comunque esce con 0.

Una modifica è una directory direttamente sotto openspec/changes/. A differenza delle specifiche, le modifiche non possono essere annidate in una cartella di namespace. Una cartella come changes/mobile/ che avvolge solo una modifica (changes/mobile/refresh-token/) viene elencata con lo stato not a change, seguita da un avviso che nomina le directory annidate. --json contrassegna quella voce con un array nested e aggiunge un array warnings al livello superiore. show, status, validate e archive rifiutano la cartella con lo stesso messaggio. Per risolvere, sposta la modifica in alto e incorpora il namespace nel suo nome:

bash

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

Codici di uscita

0: elenco stampato, anche quando vuoto.
1: nessuna root OpenSpec trovata (fuori da un progetto, nessun --store).

openspec show

Stampa una modifica o una specifica, come markdown o JSON.

bash

openspec show add-rate-limit              # modifica: stampa proposal.md
openspec show add-rate-limit --diff       # modifica: aggiunge i diff dei requisiti
openspec show api                         # specifica: stampa spec.md
openspec show api --json --no-scenarios   # JSON della specifica senza testo degli scenari

Senza un nome, show chiede modifica o specifica, poi elenca gli elementi da cui scegliere. Fuori da un terminale interattivo esce con 1 e stampa le forme dirette.

Argomenti

Argomento	Che cos'è
`item-name`	La modifica o la specifica da mostrare, per nome della cartella (`add-rate-limit`, `api`).

Opzioni

Flag	Effetto
`--json`	Stampa JSON strutturato invece di markdown grezzo.
`--type <change\|spec>`	Scegli il tipo quando una modifica e una specifica condividono un nome.
`--no-interactive`	Non chiedere mai: un nome mancante diventa un errore.
`--deltas-only`	JSON, modifica: limita l'output ai delta. Il JSON della modifica è già solo-delta, quindi l'output corrisponde al semplice `--json`.
`--requirements-only`	Alias deprecato per `--deltas-only`. Avvisa su stderr.
`--diff`	Modifica: aggiunge i diff dei delta per requisito. Ignorato con un avviso per le specifiche.
`--requirements`	JSON, specifica: mantiene il testo dei requisiti, svuota gli array `scenarios`.
`--no-scenarios`	JSON, specifica: stesso output di `--requirements`.
`-r, --requirement <id>`	JSON, specifica: output di un requisito per posizione base-1. Non può essere combinato con `--requirements`.
`--store <id>`	Usa un archivio registrato come root OpenSpec invece del progetto corrente.

I flag che non si applicano al tipo risolto vengono ignorati con un avviso su stderr.

Output

La modalità testo è un passthrough grezzo: una modifica stampa il suo proposal.md, una specifica stampa il suo spec.md.

# Add rate limiting

## Perché
I client non autenticati possono esaurire l'API.

## Cosa cambia
- Aggiungi la limitazione della frequenza per client all'API pubblica.

Per una modifica, --diff stampa prima la proposta, poi una sezione Specifications Changed (diffs). I requisiti ADDED includono il loro testo completo. I requisiti REMOVED conservano i campi Reason e Migration così come redatti. I requisiti RENAMED mostrano FROM e TO. I requisiti MODIFIED mostrano un diff unificato rispetto al requisito principale corrispondente.

Se un'intestazione MODIFIED corrisponde solo dopo aver normalizzato maiuscole/minuscole o spazi bianchi, l'output include sia il diff sia un avviso che la corrispondenza di archive è esatta. Se la specifica principale o il requisito manca, l'output avverte e stampa l'intero blocco delta. Un blocco MODIFIED senza differenze testuali stampa (no textual changes).

Una modifica con --json ha forma 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"
  }
}

Ogni requisito porta il proprio name, il testo dell'intestazione dopo Requirement:. Questo è il nome con cui archive confronta le voci MODIFIED, REMOVED e RENAMED. Ogni scenario porta il proprio name, il testo dell'intestazione dopo Scenario:. Una sequenza finale di # su una delle due intestazioni non fa parte del nome.

--json --diff mantiene questa struttura di primo livello. Un delta MODIFIED acquisisce una stringa diff, una stringa warning o entrambe. Le altre operazioni restano invariate. Una stringa diff vuota significa che i blocchi principale e delta sono testualmente identici.

Una specifica con --json elenca i propri requisiti con gli scenari. Requisiti e scenari portano gli stessi campi name del JSON di modifica:

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 nome sconosciuto suggerisce corrispondenze vicine: Unknown item 'does-not-exist'. Did you mean: add-rate-limit, api?. Un nome che corrisponde sia a una modifica sia a una specifica genera un errore e richiede --type.

Codici di uscita

0: elemento stampato.
1: nome sconosciuto o ambiguo, nessun nome fuori da un terminale, indice -r fuori intervallo, --requirements combinato con -r, oppure impossibile leggere un delta o una specifica principale per --diff.

openspec view

Stampa una dashboard di specifiche e modifiche su una singola schermata.

bash

openspec view   # riepilogo del progetto in una schermata

view stampa la dashboard una volta ed esce. Non legge alcun tasto. Le modifiche si raggruppano per avanzamento delle attività: Draft (nessuna attività ancora), Active (attività in corso, con barra di avanzamento e percentuale), Completed (ogni attività spuntata). Le specifiche sono elencate con il numero di requisiti, dalla più grande alla più piccola.

Opzioni

Flag	Effetto
`--store <id>`	Usa uno store registrato come root OpenSpec invece del progetto corrente.

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

Una riga di riepilogo Task Progress compare quando una modifica ha attività in corso.

Ogni modifica attiva mostra anche il proprio schema e gli stati degli artefatti sotto la barra di avanzamento delle attività:

text

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

Indicatore	Stato dell'artefatto
`✓`	Il suo output esiste. Un artefatto tasks esistente è considerato completato anche se la sua checklist non è completata.
`→`	È pronto per essere creato.
Nessun indicatore	È bloccato da una dipendenza mancante.
`(skipped)`	La modifica lo salta.

Se un workflow non può essere caricato, view stampa un avviso e mantiene visibile l'avanzamento delle attività di quella modifica. Esegui openspec status --change <name> per ispezionare il workflow separatamente. Dopo openspec view --store <id>, passa lo stesso --store <id> a status.

Codici di uscita

0: dashboard stampata.
1: nessuna root OpenSpec trovata (fuori da un progetto, nessun --store).

openspec validate

Verifica modifiche e specifiche per individuare problemi strutturali.

bash

openspec validate add-rate-limit   # una modifica o una specifica, per nome
openspec validate --all            # tutte le modifiche e le specifiche

Senza un nome e senza un flag bulk, validate mostra un prompt per scegliere gli elementi. Fuori da un terminale interattivo esce con 1 e stampa invece i flag bulk.

Argomenti

Argomento	Che cos'è
`item-name`	La modifica o la specifica da convalidare, per nome della cartella (`add-rate-limit`, `api`).

Opzioni

Flag	Effetto
`--all`	Convalida tutte le modifiche e tutte le specifiche.
`--changes`	Convalida ogni modifica.
`--specs`	Convalida ogni specifica.
`--archived`	Controlla il completamento delle attività nelle modifiche archiviate, senza convalidare i relativi delta di specifica applicati.
`--strict`	Tratta gli avvisi come errori.
`--type <change\|spec>`	Sceglie il tipo quando una modifica e una specifica condividono un nome.
`--json`	Stampa un report strutturato invece del testo.
`--report <mode>`	Output bulk: `full` (predefinito) o `findings`. Richiede un ambito bulk esplicito.
`--concurrency <n>`	Numero massimo di convalide parallele nelle esecuzioni bulk. Predefinito: `OPENSPEC_CONCURRENCY`, altrimenti 6.
`--no-interactive`	Non mostra mai prompt: un nome mancante o ambiguo diventa un errore.
`--store <id>`	Usa uno store registrato come root OpenSpec invece del progetto corrente.

Output

Le esecuzioni bulk stampano una riga di stato per elemento, seguita da eventuali riscontri, e terminano con i totali:

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

Riscontri sulle checkbox delle attività

L'avanzamento conta le checkbox e nient'altro, quindi un file di attività scritto come semplici punti elenco viene interpretato come zero attività: openspec list e openspec status non segnalano alcun lavoro e openspec archive non ha nulla da contrassegnare come incompleto. Validate segnala un WARNING su ogni file di attività tracciato che elenca lavoro senza una checkbox:

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'avviso viene emesso solo quando l'intero insieme tracciato della modifica non contiene alcuna checkbox. Un file di prosa accanto a una checklist reale non viene segnalato, e una modifica in fase di scrittura mantiene il proprio avanzamento nel momento in cui esiste una singola checkbox. --strict trasforma l'avviso in un errore. Il numero di riga è nel report --json.

I blocchi delimitati, i commenti HTML, il front matter YAML e il codice indentato non vengono analizzati, quindi un esempio di terminale incollato non viene mai scambiato per un elenco di attività.

Riscontri sul merge di archive

Per le modifiche, validate esegue il generatore di merge di archive rispetto alle specifiche principali correnti senza scrivere file. Segnala i conflitti di merge, come un target MODIFIED mancante o un requisito ADDED in conflitto, come INFO:

text

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

Questi riscontri compaiono anche quando la convalida ha esito positivo, sia nell'output testuale sia in quello JSON. INFO non modifica mai il codice di uscita, anche con --strict: un target mancante può appartenere a una modifica sorella non ancora archiviata. I delta già sincronizzati nelle specifiche principali seguono le regole di merge esistenti di archive.

Questa verifica non esegue la successiva convalida delle specifiche unite di archive né i controlli di dismissione. Un report pulito non garantisce che archive avrà successo.

Se il preflight di merge non può avviarsi, un riscontro INFO ne spiega il motivo. I riscontri di convalida esistenti e il codice di uscita restano invariati.

Un elemento non valido elenca ogni problema e la relativa correzione:

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 stampa un unico report per l'esecuzione:

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

Le voci issues hanno un level pari a ERROR, WARNING o INFO.

Codici di uscita

0: ogni elemento convalidato ha superato la convalida, incluso un ambito bulk vuoto.
1: un elemento non ha superato la convalida, la richiesta di report non è valida, openspec/config.yaml non può essere letto o non è YAML valido, oppure l'esecuzione non è riuscita (ad esempio un nome sconosciuto o nessuna root OpenSpec). Una configurazione che non può essere letta o analizzata interrompe l'esecuzione prima che qualsiasi elemento venga controllato; con --json viene segnalata come singola voce status con il codice unreadable_config o unparseable_config.

--report full|findings

Seleziona l'output per un ambito di convalida bulk esplicito:

full: ogni elemento. È il valore predefinito. --report full esplicito mantiene la forma di output esistente senza aggiungere metadati del report.
findings: solo gli elementi con problemi, inclusi gli elementi che superano la convalida ma hanno avvisi o informazioni. Ogni elemento viene comunque convalidato. I totali, il comportamento della modalità strict e i codici di uscita restano invariati.

bash

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

Ambiti

Flag	`report.scope` dei riscontri
`--all`	`all`
`--changes`	`changes`
`--specs`	`specs`
`--changes --specs`, o `--all` con uno dei due flag	`all`
`--archived`	`archived`

Entrambe le modalità di report esplicite rifiutano un nome di elemento posizionale, un ambito bulk mancante o ambiti archiviati e attivi combinati.

Output testuale dei riscontri

Output leggibile: stdout stampa Scope: <scope> (<count> items), poi i totali. Quando non ci sono elementi con problemi:

text

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

Le etichette degli elementi con problemi, le etichette di gravità, i percorsi e i messaggi vengono stampati su stderr. I fallimenti nell'ambito attivo mantengono il suggerimento di riesecuzione Details: dopo i totali. Il banner della root esistente e l'output di avanzamento possono precedere il report.

Output JSON dei riscontri

--report findings --json stampa un unico documento. Questo esempio ha due elementi puliti:

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 e report.version: identificano la forma validation-findings, versione 1.0. Non esiste un version o items di primo livello.
report.returnedItems e report.totalItems: contano rispettivamente i record restituiti e tutti gli elementi convalidati.
itemFindings: record completi degli elementi il cui array issues non è vuoto. Include problemi ERROR, WARNING e INFO. Ogni record conserva id, type, valid, issues e durationMs. Gli elementi archiviati usano type: "change".
summary: totali dell'intera esecuzione e conteggi per tipo, non conteggi del sottoinsieme restituito. Un ambito vuoto ha totali pari a zero ed esce con 0.
root: gli stessi metadati della root selezionata del report completo.

Conservazione dei record: gli elementi restituiti mantengono l'ordine del report completo e qualsiasi campo aggiuntivo sugli elementi o sui problemi. Il filtraggio non riscrive messaggi o posizioni, inclusi i campi opzionali line e column.

Fallimenti del comando: i fallimenti nella selezione della root o nell'individuazione degli elementi mantengono la diagnostica status esistente ed escono con 1. Non restituiscono un report dei riscontri completato né un report vuoto riuscito.

Richieste di report non valide

Entrambe le modalità di report esplicite rifiutano queste richieste prima della selezione della root o dell'individuazione degli elementi:

Un valore di report non supportato, inclusa una stringa vuota.
Un nome di elemento posizionale, anche con un flag bulk.
Nessun ambito bulk esplicito.
--archived combinato con --all, --changes o --specs.

In modalità JSON, una richiesta rifiutata esce con 1 con un solo array status a singolo elemento. Non ha root né payload del report:

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."
    }
  ]
}

La modalità leggibile stampa l'errore su stderr. Un --report senza valore è un errore di sintassi di Commander su stderr, anche con --json; non usa questa struttura diagnostica.

Filtrare esternamente un report completo

Per una vista JSON personalizzata, filtra il report completo con jq o PowerShell. Questi esempi di script conservano il codice di uscita della convalida e lasciano intatti i documenti di errore del comando.

In Bash con 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"

In 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

Queste viste personalizzate mantengono le chiavi del report completo ma omettono gli elementi puliti. Non sono né report full-v1 completi né la forma con versione di --report findings.

openspec archive

Sposta una modifica completata nell'archivio e aggiorna le specifiche principali.

bash

openspec archive add-rate-limit -y                # archivia una modifica, unisce i suoi delta
openspec archive add-rate-limit -y --skip-specs   # archivia senza toccare le specifiche

Senza un nome, archive ti chiede di scegliere una modifica. Al di fuori di un terminale interattivo termina con codice 1 e stampa invece il comando da rieseguire.

Argomenti

Argomento	Che cos'è
`change-name`	La modifica da archiviare, tramite nome della cartella (`add-rate-limit`).

Opzioni

Flag	Effetto
`-y, --yes`	Risponde sì a ogni conferma: aggiornamenti delle specifiche, attività incomplete, validazione saltata.
`--skip-specs`	Archivia senza toccare le specifiche principali (modifiche a infrastruttura, strumenti o solo documentazione).
`--no-validate`	Salta la validazione. Archive ti chiede prima di confermare e `-y` risponde affermativamente.
`--json`	Stampa un risultato strutturato invece del testo. Richiede `--yes` per confermare gli aggiornamenti delle specifiche.
`--store <id>`	Usa uno store registrato come radice OpenSpec invece del progetto corrente.

Output

Un'esecuzione riuscita riporta lo stato delle attività, mostra un'anteprima degli aggiornamenti delle specifiche, li applica e indica il nome della cartella di archivio:

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

La cartella della modifica viene spostata integralmente in openspec/changes/archive/2026-08-11-add-rate-limit/, con la data odierna anteposta al suo nome. Ogni delta viene unito alla relativa specifica principale: il requisito ADDED sopra è stato aggiunto in coda a openspec/specs/api/spec.md. Senza -y, archive mostra l'anteprima e chiede conferma prima di aggiornare. Rifiutando, la modifica viene comunque archiviata e le specifiche restano invariate.

Con --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 valida prima la modifica e rifiuta quelle che non superano la validazione:

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.

Le attività incomplete generano un avviso ma non bloccano. In modalità interattiva, archive chiede se continuare, mentre -y continua automaticamente:

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

Codici di uscita

0: la modifica è stata archiviata, con o senza aggiornamenti delle specifiche.
1: la validazione non è riuscita, il nome della modifica è sconosciuto oppure era necessaria una conferma e non è stato possibile leggere una risposta.

openspec new

Crea una nuova cartella di modifica.

bash

openspec new change add-caching                                # solo metadati
openspec new change add-search --goal "Users can search docs"  # registra un obiettivo

new ha un solo sottocomando, new change <name>. Crea openspec/changes/<name>/ contenente un unico file di metadati .openspec.yaml:

yaml

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

Gli artefatti (proposta, specifiche, design, attività) non vengono creati automaticamente qui. Li scrivi in seguito e openspec status ti indica qual è il prossimo.

Argomenti

Argomento	Che cos'è
`name`	Nome della cartella per la modifica (`add-caching`).

Opzioni

Flag	Effetto
`--description <text>`	Crea anche un `README.md` nella cartella della modifica con questo testo.
`--goal <text>`	Memorizza una riga `goal:` in `.openspec.yaml`.
`--schema <name>`	Schema di workflow per la modifica. Predefinito: `spec-driven`, l'unico schema fornito.
`--json`	Stampa la modifica creata come JSON invece che come testo.
`--store <id>`	Usa uno store registrato come radice OpenSpec invece del progetto corrente.

Output

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

Quando non viene trovata alcuna cartella openspec/, new change ne crea una nella posizione corrente e lo segnala:

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.

L'avviso viene inviato a stdout insieme al resto dell'output per l'utente e non compare mai con --json.

Con --json, in un progetto che ha già 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"
  }
}

Quando non viene trovata alcuna cartella openspec/ e new change ne crea una, il JSON ha la stessa struttura. root.path è la cartella da cui hai eseguito il comando e root.source riporta implicit:

json

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

Codici di uscita

0: modifica creata.
1: la modifica esiste già oppure lo schema è sconosciuto.

openspec status

Riporta lo stato di completamento degli artifact per una singola change o per tutte le change attive.

bash

openspec status --change add-rate-limit          # vista checklist
openspec status --change add-rate-limit --json   # report strutturato
openspec status --all                            # tutte le change attive
openspec status --all --json                     # un unico report batch

Quando esistono change attive, usare esattamente una tra --change e --all. Se nessuna delle due viene specificata, status esce con codice 1 ed elenca le change disponibili, anche quando ne esiste solo una:

text

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

Quando il progetto non ha change attive, status stampa No active changes. Create one with: openspec new change <name> ed esce con codice 0 anche senza nessuno dei due flag. Con --all --json, lo stesso stato vuoto è { "changes": [], "message": "No active changes.", "root": ... }.

Opzioni

Flag	Effetto
`--change <id>`	La change di cui riportare lo stato, identificata dal nome della cartella.
`--all`	Riporta lo stato di tutte le change attive, ordinate per nome. Non può essere combinato con `--change`.
`--schema <name>`	Sovrascrive lo schema rilevato automaticamente da `openspec/config.yaml`. Un nome sconosciuto costituisce un errore.
`--json`	Stampa un report strutturato invece del testo.
`--store <id>`	Usa uno store registrato come radice OpenSpec invece del progetto corrente.

Output

Una checklist degli artifact dello schema: [x] completato, [ ] pronto per la scrittura, [-] bloccato finché gli artifact da cui dipende non esistono.

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 riga Next: indica l'unico comando che fa avanzare la change, quindi openspec status è sufficiente per riprendere una change in una nuova sessione. Indica il prossimo artifact pronto finché la pianificazione non è conclusa, e openspec instructions apply quando tutti gli artifact di pianificazione esistono:

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

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

Include --store <id> ogni volta che la radice risolta è uno store, e indica lo stesso comando citato nella frase nextSteps del JSON.

--json aggiunge le dipendenze per ogni artifact, i percorsi dei file risolti e un prossimo passo suggerito. Versione abbreviata:

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

Con --all --json, changes contiene lo stesso oggetto di stato per ogni change, senza un root per singola change. La radice selezionata compare una sola volta nell'oggetto principale. Questo esempio omette i campi di stato per change mostrati sopra:

json

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

Se una change non può essere caricata, il batch continua. La sua voce contiene changeName e un messaggio diagnostico in status, mentre le altre voci restano disponibili. Il comando esce con codice 1, anche in modalità JSON, così che la CI non consideri riuscito un report incompleto. L'output JSON rimane un unico documento interpretabile.

Codici di uscita

0: ogni stato richiesto è stato stampato; anche un report --all vuoto esce con codice 0.
1: una change richiesta non è stata caricata, --change o --all manca, i due flag sono stati usati insieme, la change non esiste, oppure l'override dello schema è sconosciuto.

openspec instructions

Stampa le istruzioni per creare un artifact, applicare una change o archiviarla. Il tuo agente esegue questo comando durante il workflow per recuperare il testo delle istruzioni del suo prossimo passo.

bash

openspec instructions proposal --change add-rate-limit   # come scrivere un artifact
openspec instructions apply --change add-rate-limit      # come implementare la change
openspec instructions archive --change add-rate-limit    # input per l'archiviazione

Argomenti

Argomento	Descrizione
`artifact`	Un id di artifact dello schema (`proposal`, `specs`, `design`, `tasks` in `spec-driven`), oppure le parole riservate `apply` e `archive`.

Opzioni

Flag	Effetto
`--change <id>`	La change per cui generare le istruzioni. Obbligatorio.
`--schema <name>`	Sovrascrive lo schema. In assenza, viene rilevato automaticamente da `config.yaml`.
`--json`	Stampa un oggetto strutturato invece del testo.
`--store <id>`	Usa uno store registrato come radice OpenSpec invece del progetto corrente.

Output

La modalità artifact stampa un unico blocco di istruzioni: il task, il file da scrivere, come scriverlo, il template dell'artifact e cosa viene sbloccato dal suo completamento.

<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 stampa i file di contesto, l'avanzamento dei task e l'istruzione operativa:

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

Quando gli artifact richiesti mancano, apply riporta invece ### ⚠️ Blocked indicandoli. archive stampa il nome della change più l'eventuale contesto di progetto e la guida operativa presenti nella config. Se non ne è configurato nessuno, lo comunica e non aggiunge altro.

Con --json, ogni modalità restituisce un unico oggetto. La modalità artifact inizia così:

json

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

e prosegue con outputPath, existingOutputPaths, le stringhe complete di instruction e template, dependencies, unlocks e root. La modalità apply contiene contextFiles, progress, tasks, taskTrackingConfigured, state (blocked, ready, all_done) e instruction.

Ogni voce di tasks contiene id, description, done, sourcePath e line. sourcePath è il percorso assoluto del file tracciato che ha fornito il task. line è il numero di riga (a partire da 1) della casella di controllo del task in quel file.

taskTrackingConfigured è sempre un booleano: true quando lo schema imposta un apply.tracks non nullo, anche se nessun file corrisponde, e false altrimenti. Se un file di tracciamento corrispondente non può essere letto, unavailableTrackingFiles contiene il suo path assoluto e la reason dell'errore. Questo campo è omesso quando tutti i file corrispondenti sono leggibili. I file leggibili contribuiscono comunque a tasks e progress, ma state non può essere all_done finché non è stato letto ogni file corrispondente.

Codici di uscita

0: istruzioni stampate.
1: artifact sconosciuto, change sconosciuta, schema sconosciuto oppure --change mancante. Ogni errore elenca i valori validi.

openspec templates

Stampa i percorsi dei template risolti per gli artefatti di uno schema.

bash

openspec templates          # schema predefinito: spec-driven
openspec templates --json   # mappa dagli ID degli artefatti ai percorsi

Opzioni

Opzione	Effetto
`--schema <name>`	Schema da risolvere. Predefinito: `spec-driven`.
`--json`	Stampa una mappa JSON che associa gli ID degli artefatti ai percorsi dei template.

Output

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 indica da dove è stato risolto lo schema: project (openspec/schemas/ nel tuo progetto), user (un override globale) o package (integrato nella CLI). Il progetto ha la precedenza sull'utente, l'utente sul pacchetto.

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

Codici di uscita

0: percorsi stampati.
1: schema sconosciuto. L'errore elenca gli schemi disponibili.

openspec schemas

Elenca gli schemi di workflow disponibili.

bash

openspec schemas          # nomi, descrizioni, ordine degli artefatti
openspec schemas --json   # leggibile dalla macchina, per uso da parte degli agenti

Opzioni

Opzione	Effetto
`--json`	Stampa l'output in JSON (per uso da parte degli agenti).

Output

Available schemas:

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

Gli schemi del tuo progetto sono etichettati come (project) e gli override globali come (user override).

json

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

Codici di uscita

0: schemi elencati.
1: non è stato possibile leggere l'elenco degli schemi.

openspec schema

Ispeziona, crea un fork o crea uno schema (sperimentale). Ogni sottocomando stampa prima Note: Schema commands are experimental and may change. su stderr.

bash

openspec schema which spec-driven          # dove viene risolto uno schema
openspec schema fork spec-driven my-flow   # copia uno schema nel progetto
openspec schema init my-schema             # crea uno schema da zero

Sottocomando	Cosa fa
`which`	Mostra da dove viene risolto uno schema.
`validate`	Verifica la struttura e i template di uno schema.
`fork`	Copia uno schema esistente nel progetto per la personalizzazione.
`init`	Crea un nuovo schema locale del progetto.

Gli schemi vengono risolti da tre posizioni. Vale la prima corrispondenza:

Sorgente	Posizione
`project`	`openspec/schemas/` nel progetto corrente.
`user`	`~/.local/share/openspec/schemas/` (`XDG_DATA_HOME` e Windows `%LOCALAPPDATA%` rispettati).
`package`	Gli schemi distribuiti con la CLI. `spec-driven` si trova qui.

openspec schema which

Mostra quale copia di uno schema la CLI utilizzerà.

bash

openspec schema which spec-driven
openspec schema which --all        # ogni schema, raggruppato per sorgente

Argomenti

Argomento	Cos'è
`name`	Lo schema da cercare. Obbligatorio a meno che non sia impostato `--all`. Senza nessuno dei due, which esce con codice 1.

Opzioni

Flag	Effetto
`--all`	Elenca ogni schema con la sua sorgente di risoluzione.
`--json`	Stampa la risoluzione in formato JSON.

Output

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

Quando una copia con priorità più alta ne nasconde un'altra, una sezione Shadows: elenca le copie nascoste. Con --json:

json

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

Un nome sconosciuto esce con codice 1 e elenca gli schemi disponibili.

openspec schema validate

Verifica la struttura e i template di uno schema.

bash

openspec schema validate spec-driven   # uno schema, da qualsiasi sorgente
openspec schema validate               # ogni schema locale del progetto

Verifica che schema.yaml esista e sia parsificabile, che la struttura corrisponda al formato dello schema, che il file di template di ogni artefatto esista nella directory templates/ dello schema e che il grafo delle dipendenze non abbia cicli o riferimenti sconosciuti, inclusi quelli in apply.requires. Un valore apply.tracks che non corrisponde esattamente al valore generates di qualche artefatto stampa una riga warning: ma non fa fallire la validazione, perché OpenSpec in tal caso non può determinare a quale artefatto appartiene il progresso di quel file.

Opzioni

Flag	Effetto
`--json`	Stampa un report strutturato invece del testo.
`--verbose`	Stampa ogni passaggio di validazione.

Output

✓ Schema 'spec-driven' is valid

Senza un nome, ogni schema del progetto riceve una riga sotto un'intestazione Validation Results:. Uno schema con errori elenca i propri problemi e l'esecuzione esce con codice 1:

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

openspec schema fork

Copia uno schema esistente nel progetto per consentirne la personalizzazione.

bash

openspec schema fork spec-driven my-flow

Argomenti

Argomento	Cos'è
`source`	Lo schema da copiare, da qualsiasi posizione.
`name`	Nome per la copia. Kebab-case (`my-workflow`). Predefinito: `<source>-custom`.

Opzioni

Flag	Effetto
`--force`	Sovrascrive uno schema di destinazione esistente.
`--json`	Stampa il risultato in formato JSON.

Output

✔ 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

Il fork viene posizionato in openspec/schemas/, e il campo name: nel suo schema.yaml viene riscritto con il nuovo nome:

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

Una destinazione esistente è un errore a meno che non si passi --force. Un fork che mantiene il nome della sorgente oscura l'originale.

openspec schema init

Crea un nuovo schema locale del progetto con template iniziali.

bash

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

Senza --description e senza --artifacts in un terminale interattivo, init richiede una descrizione, una checklist di artefatti e se impostare lo schema come predefinito del progetto. Fuori da un terminale utilizza i valori predefiniti di seguito.

Argomenti

Argomento	Cos'è
`name`	Nome per il nuovo schema. Kebab-case (`my-workflow`).

Opzioni

Flag	Effetto
`--description <text>`	Descrizione dello schema. Predefinito: `Custom workflow schema for <name>`.
`--artifacts <list>`	ID di artefatti separati da virgola tra `proposal`, `specs`, `design`, `tasks`. Predefiniti: tutti e quattro.
`--default`	Scrive `schema: <name>` nel file `openspec/config.yaml` o `openspec/config.yml` esistente. Crea `openspec/config.yaml` se nessuno dei due esiste. I nuovi cambiamenti utilizzeranno questo schema.
`--no-default`	Salta la richiesta relativa all'impostazione predefinita.
`--force`	Sovrascrive uno schema esistente con lo stesso nome.
`--json`	Stampa il risultato in formato JSON.

La creazione dello schema e l'aggiornamento della configurazione --default sono un'unica operazione. Se OpenSpec non riesce a validare o scrivere la configurazione, lascia invariati sia la configurazione sia eventuali schemi esistenti.

Output

✔ Created schema 'my-schema'

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

Artifacts: proposal, tasks

Il layout su disco:

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

schema.yaml collega gli artefatti selezionati con le relative dipendenze. Quando tasks è incluso, riceve anche una fase apply che traccia tasks.md. Utilizza lo schema con openspec new --schema my-schema.

openspec store

Crea e gestisce store: repository OpenSpec standalone registrati sulla tua macchina.

bash

openspec store setup team-context --path ~/openspec/team-context   # crea e registra
openspec store register ~/stores/design-system                     # registra un checkout esistente
openspec store list                                                # visualizza i registrati

Le registrazioni risiedono in un registro per-macchina: ~/.local/share/openspec/stores/registry.yaml, oppure $XDG_DATA_HOME/openspec/stores/registry.yaml quando XDG_DATA_HOME è impostato. Ogni sottocomando accetta --json per stampare un report strutturato invece del testo. Eseguire openspec store con un sottocomando mancante o sconosciuto esce con codice 1 e elenca i sottocomandi.

Sottocomando	Cosa fa
`setup [id]`	Crea una cartella store e la registra.
`register [path]`	Registra una cartella store esistente.
`unregister <id>`	Dimentica la registrazione. La cartella rimane su disco.
`remove <id>`	Dimentica la registrazione ed elimina la cartella.
`list` (alias `ls`)	Elenca gli store registrati.
`doctor [id]`	Verifica registrazione, metadati e stato Git per gli store registrati.

openspec store setup

Crea una cartella store e la registra.

bash

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

In un terminale interattivo, setup richiede nome e posizione mancanti e chiede conferma prima di creare qualsiasi cosa. Fuori da un terminale, un nome o un --path mancante fa uscire con codice 1 indicando il flag da passare. Rieseguire setup per uno store già registrato riporta Registry: already registered.

Setup esce con codice 1 con store_setup_inside_git_repo quando --path si trova all'interno di un altro repository Git, perché inizializzare lo store lì comporterebbe l'annidamento di un repository dentro un altro. --no-init-git non crea alcun repository, quindi salta quel controllo. Usalo per mantenere uno store in ~/openspec/<id> quando la tua home directory è a sua volta un repository Git, ad esempio un repository dotfiles.

Argomenti

Argomento	Cos'è
`id`	Il nome dello store. Diventa l'id che passi a `--store`.

Opzioni

Flag	Effetto
`--path <path>`	Cartella in cui deve risiedere lo store (`~` viene espanso).
`--init-git`	Inizializza un repository Git con un commit iniziale. Predefinito.
`--no-init-git`	Salta ogni azione Git: nessuna inizializzazione, nessun commit iniziale.
`--remote <url>`	Sorgente di clone canonica registrata in `store.yaml`.

Output

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 riporta cosa è stato creato e dove è stato registrato:

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

Registra una cartella store esistente, ad esempio lo store di un collega che hai clonato.

bash

openspec store register ~/stores/design-system

La cartella deve contenere una root openspec/ valida. Con .openspec-store/store.yaml presente, register riutilizza l'id registrato. Senza tale file, register chiede conferma prima di creare quei metadati. Fuori da un terminale interattivo, passare --yes. Una macchina può registrare un checkout per store id. Un secondo percorso con lo stesso id, oppure lo stesso percorso con un secondo id, fa uscire con codice 1.

Argomenti

Argomento	Cos'è
`path`	La cartella store da registrare (`~` viene espanso). Obbligatorio.

Opzioni

Flag	Effetto
`--id <id>`	Store id. Predefinito: metadati o nome della cartella.
`--yes`	Conferma la creazione dei metadati di identità dello store per una root OpenSpec valida.

Output

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

--json stampa la stessa struttura del documento di store setup --json.

openspec store unregister

Dimentica la registrazione. La cartella rimane su disco.

bash

openspec store unregister design-system

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

openspec store remove

Dimentica la registrazione ed elimina la cartella.

bash

openspec store remove design-system --yes

In modo interattivo, remove chiede conferma prima di eliminare. Con --json o fuori da un terminale interattivo, l'eliminazione richiede --yes:

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

Remove esce con codice 1 e non elimina nulla quando la cartella non contiene metadati dello store corrispondenti, oppure quando contiene un altro store registrato (ad esempio uno store incluso come sottomodulo Git). In tal caso l'errore è store_remove_contains_registered_store: eseguire prima openspec store unregister <nested-id>, oppure openspec store unregister <id> per dimenticare lo store senza eliminare i file.

Opzioni

Flag	Effetto
`--yes`	Conferma l'eliminazione della cartella store locale.

Output

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

openspec store list

Elenca gli store registrati. ls è 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

Senza alcuno store registrato, list stampa No stores registered. e i comandi setup e register da eseguire successivamente.

openspec store doctor

Verifica registrazione, metadati e stato Git per gli store registrati.

bash

openspec store doctor                # ogni store registrato
openspec store doctor team-context  # uno store

Output

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

Codici di uscita

0: il report è stato stampato, anche quando uno store segnala problemi.
1: il report non è stato eseguito (ad esempio uno store id sconosciuto).

openspec doctor

Riporta lo stato di integrità delle relazioni per la radice OpenSpec risolta.

bash

openspec doctor                       # la radice openspec/ più vicina sopra la tua cwd
openspec doctor --store team-context  # uno store registrato come radice

Doctor è di sola lettura: non clona, sincronizza né ripara mai. Riporta se la radice è integra e se ogni riferimento dichiarato in openspec/config.yaml si risolve su questa macchina. Se non c'è nessuna radice sopra la tua cwd e non viene passato --store, termina con codice 1 e elenca i tuoi store registrati.

Opzioni

Flag	Effetto
`--store <id>`	Usa uno store registrato come radice OpenSpec al posto del progetto corrente.
`--json`	Stampa il report di integrità come JSON.

Output

Doctor

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

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

Con --store, la radice è lo store e il report aggiunge una riga per lo store:

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)

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

Codici di uscita

0: il report è stato stampato, anche quando elenca problemi.
1: nessuna radice risolta (nessuna openspec/ sopra la tua cwd e nessun --store), oppure un id --store sconosciuto.

openspec context

Stampa il contesto di lavoro per la radice OpenSpec risolta: la radice più ogni store referenziato dichiarato in openspec/config.yaml, ciascuno con un comando di fetch.

bash

openspec context                       # la radice openspec/ più vicina sopra la tua cwd
openspec context --store team-context  # uno store registrato come radice
openspec context --json                # brief per l'agente

I riferimenti che non si risolvono su questa macchina compaiono in una sezione Not available on this machine, ciascuno con una correzione.

Opzioni

Flag	Effetto
`--store <id>`	Usa uno store registrato come radice OpenSpec al posto del progetto corrente.
`--json`	Stampa il brief per l'agente come JSON.
`--code-workspace <path>`	Scrive anche un file workspace di VS Code per l'insieme.
`--force`	Sovrascrive un file `--code-workspace` esistente.

Output

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

Con --store, lo store è l'intero insieme:

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.

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

Scrittura di un file workspace

--code-workspace scrive un file workspace di VS Code nel percorso che indichi: una cartella per la radice, una cartella ref:<id> per ogni store referenziato disponibile. I riferimenti non disponibili vengono saltati e indicati nella riga di riepilogo, Wrote /Users/you/projects/my-app/openspec.code-workspace (2 folders). Il riepilogo viene stampato su stderr, così che lo stdout di --json resti un unico documento JSON. Se il file esiste già, l'operazione termina con codice 1 a meno che non venga passato --force.

json

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

Codici di uscita

0: il report è stato stampato.
1: nessuna radice risolta (nessuna openspec/ sopra la tua cwd e nessun --store), oppure la scrittura di --code-workspace è stata rifiutata.

openspec workset

Compone, conserva e apre viste di lavoro personali. Un workset è un elenco salvato e denominato di cartelle su cui lavori insieme.

bash

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

Sottocomando	Cosa fa
`create [name]`	Compone e salva una vista di lavoro denominata delle cartelle scelte.
`list`, `ls`	Mostra i workset salvati con i relativi membri.
`open <name>`	Apre un workset salvato nel tuo strumento (finestra dell'editor o sessione dell'agente).
`remove <name>`	Elimina un workset salvato (le cartelle dei membri non vengono mai toccate).

Un workset è puramente locale:

Il suo stato risiede in una sola cartella: ~/.local/share/openspec/worksets/ ($XDG_DATA_HOME/openspec/worksets/ quando impostata; %LOCALAPPDATA%\openspec\worksets\ su Windows).
Nelle cartelle dei membri non viene scritto nulla e nulla viene sottoposto a commit o condiviso.
Eliminando quella sola cartella si rimuove ogni traccia.

openspec workset create

Salva una vista di lavoro denominata delle cartelle.

bash

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

In un terminale interattivo, create richiede tutto ciò che i flag non hanno fornito: il nome, le cartelle una alla volta, uno strumento, poi propone di aprire subito il workset. Fuori da un terminale interattivo, un nome o un membro mancante è un errore. Un nome già salvato è sempre un errore. Rimuovilo prima.

Argomenti

Argomento	Che cos'è
`name`	Il nome del workset. Kebab-case: lettere minuscole, numeri, trattini singoli. Obbligatorio fuori da un terminale interattivo.

Opzioni

Flag	Effetto
`--member <member>`	Cartella membro come `<path>` o `<name>=<path>`, ripetibile. La prima è quella primaria. Il percorso deve essere una cartella esistente e l'etichetta predefinita è il nome della cartella stessa.
`--tool <id>`	Strumento preferito con cui aprire questo workset. ID integrati: `code` (VS Code), `cursor` (Cursor). `claude` e `codex` sono temporaneamente disabilitati.
`--json`	Stampa il workset salvato come JSON.

Output

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

openspec workset list

Mostra i workset salvati con i relativi membri, ordinati per nome.

bash

openspec workset list   # alias: ls

Opzioni

Flag	Effetto
`--json`	Stampa i workset come JSON.

Output

Un blocco per workset: il nome, il suo strumento quando presente, quindi una riga name path per ogni membro. Se non c'è nulla di salvato, list stampa 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

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

Apre un workset salvato nel tuo strumento. Gli strumenti editor (code, cursor) ricevono un file .code-workspace generato. Si apre una finestra e il comando termina. Gli strumenti agente CLI (claude, codex) prenderebbero il controllo di questo terminale con ogni membro collegato. Sono temporaneamente disabilitati mentre quel flusso viene rielaborato, quindi per ora i workset si aprono in un IDE.

bash

openspec workset open checkout                # strumento salvato, oppure un prompt
openspec workset open checkout --tool cursor  # questo strumento solo per questa volta

Argomenti

Argomento	Che cos'è
`name`	Il workset da aprire.

Opzioni

Flag	Effetto
`--tool <id>`	Apri con questo strumento solo per questa volta.

Senza --tool e senza uno strumento salvato, open ti chiede di scegliere uno strumento installato. Fuori da un terminale interattivo, esce invece con 1.

Una cartella membro che non esiste più viene saltata con un avviso. Quando manca quella primaria, il successivo membro ancora esistente diventa quello primario per questa apertura. Quando non esiste nessuna cartella membro, l'apertura fallisce.
--json viene rifiutato: open cede il terminale allo strumento e non ha una modalità JSON.
Quando l'avvio fallisce, l'errore termina con la procedura manuale: il percorso del file workspace e l'elenco dei membri.

Codici di uscita

Rispecchia lo strumento: il comando esce con il codice di uscita dello strumento stesso e un segnale diventa 128+n (130 dopo Ctrl-C).
1: workset sconosciuto, nessuna cartella membro disponibile o nessuno strumento utilizzabile.

openspec workset remove

Elimina un workset salvato e il relativo file .code-workspace generato. Le cartelle dei membri non vengono mai toccate.

bash

openspec workset remove checkout --yes

In un terminale interattivo, remove mostra il workset e ti chiede conferma. Con --json, oppure fuori da un terminale, richiede --yes ed esce con 1 se non è presente.

Opzioni

Flag	Effetto
`--yes`	Conferma la rimozione in modalità non interattiva.
`--json`	Stampa la rimozione come JSON.

Output

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

openspec version

Indica la versione di OpenSpec in esecuzione e come è stata installata questa copia.

bash

openspec version                 # versione locale e dettagli di installazione
openspec version --json          # report locale strutturato
openspec version --check         # controlla anche il registry per un aggiornamento
openspec version --check --json  # report strutturato locale e aggiornamenti

Senza --check, questo comando è locale e non contatta alcun registry. Funziona anche fuori da un progetto OpenSpec. Il flag esistente openspec --version resta la forma più breve e stampa solo il numero di versione.

Opzioni

Flag	Effetto
`--json`	Stampa un unico documento JSON versionato invece del testo.
`--check`	Controlla il registry configurato per una release più recente.

Output

Per un'installazione npm globale:

text

OpenSpec 1.13.2 (npm, global)

L'ambito di installazione è global, project, temporary per un runner effimero come npx, source per un checkout, oppure standalone per l'installazione standalone. OpenSpec omette i dettagli che non riesce a identificare invece di indovinare.

--json mantiene i dettagli sconosciuti come valori null espliciti:

json

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

Con --check, un aggiornamento disponibile aggiunge l'ultima versione e un comando quando OpenSpec riesce a identificare un comando sicuro per quell'installazione:

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

Valori dello stato di aggiornamento:

Stato	Significato
`available`	Il registry ha restituito una versione sicura più recente di quella in esecuzione.
`current`	Il controllo è stato completato e non ha trovato versioni più recenti.
`disabled`	Un'impostazione esistente sulla privacy o sul controllo degli aggiornamenti ha bloccato l'accesso al registry. `latest` è `null`.
`offline`	Il registry non era disponibile o ha restituito una risposta inutilizzabile. `latest` è `null`.

Per l'installazione standalone, il comando di aggiornamento è openspec install.

DO_NOT_TRACK, gli opt-out della telemetria, OPENSPEC_NO_UPDATE_CHECK, il rilevamento della CI e gli override del registry non-HTTPS rifiutati disabilitano il controllo. I controlli disabilitati e offline escono comunque con 0 perché la disponibilità di aggiornamenti ha solo valore indicativo. Questo comando non aggiorna mai OpenSpec; canSelfUpgrade indica soltanto se il percorso esistente openspec update potrebbe aggiornare in sicurezza questa copia.

Codici di uscita

0: il report locale è stato stampato, inclusi i controlli di aggiornamento disabilitati o offline.
1: la sintassi del comando non era valida, ad esempio l'opzione --upgrade non supportata.

openspec install

Installa il openspec autonomo. Eseguilo da un'installazione npm o Homebrew per passare ad esso, oppure dall'installazione autonoma per aggiornarlo sul posto.

bash

openspec install          # versione più recente
openspec install 1.15.0   # una versione specifica

Esegue lo script di installazione, che seleziona la versione più recente i cui file sono tutti allegati e il file per la tua macchina, e lo verifica rispetto ai SHA256SUMS di quella versione:

Da un gestore di pacchetti: installa in ~/.local/bin (Windows: %LOCALAPPDATA%\Programs\openspec) e stampa il comando che rimuove la vecchia copia, come npm uninstall -g @fission-ai/openspec. Non rimuove mai quella copia da solo.
Dall'installazione autonoma: sostituisce il file in esecuzione dove si trova, con il proprio nome.

Successivamente indica quale copia di openspec ora viene eseguita, poiché una copia del gestore di pacchetti presente prima nel tuo PATH continua a essere eseguita finché non la rimuovi.

Argomenti

Argomento	Cosa è
`version`	Versione da installare, come `1.15.0`. Opzionale; per impostazione predefinita è la più recente.

OPENSPEC_INSTALL_DIR e OPENSPEC_INSTALL_NAME scelgono un'altra cartella o nome file.

Codici di uscita

0: installato.
1: la versione non è una versione di rilascio, oppure il download o l'installazione non sono riusciti. La tua copia attuale rimane com'era.

openspec feedback

Invia feedback su OpenSpec.

bash

openspec feedback "L'output di convalida è difficile da scansionare"
openspec feedback "L'archiviazione fallisce su Windows" --body "Passaggi: init, propose, archive. Errore: EPERM."

La CLI archivia il tuo messaggio come issue GitHub sul repository Fission-AI/OpenSpec tramite la tua CLI gh. Il titolo diventa Feedback: <messaggio>. Il corpo utilizza le intestazioni del modulo bug: il tuo messaggio sotto What happened, il testo di --body sotto Details e una sezione Minimal steps to reproduce che ti chiede di aggiungere i passaggi, poiché la CLI non può compilarli. Un piè di pagina aggiunge versione CLI, piattaforma e timestamp. L'issue riceve l'etichetta feedback. Se il repository non definisce tale etichetta, la CLI riprova senza di essa e lo segnala.

Argomenti

Argomento	Cosa è
`message`	Riepilogo di una riga. Diventa il titolo dell'issue. Obbligatorio.

Opzioni

Flag	Effetto
`--body <testo>`	Descrizione più lunga aggiunta al corpo dell'issue.

Output

In caso di successo:

✓ Feedback inviato con successo!
URL dell'issue: https://github.com/Fission-AI/OpenSpec/issues/1234

Senza gh installato, o con gh non autenticato, non viene inviato nulla. La CLI stampa il tuo feedback formattato tra i marcatori --- FORMATTED FEEDBACK ---, poi un link che apre il modulo di segnalazione bug con titolo, cosa è successo (il tuo messaggio e il testo di --body), versione CLI e ambiente (piattaforma e versione Node) compilati. Completi il resto del modulo nel browser. Il percorso non autenticato aggiunge Per inviare automaticamente in futuro: gh auth login.

Codici di uscita

0: issue creata, oppure è stato eseguito il fallback di invio manuale (nessun gh, o gh non autenticato).
1: nessun messaggio fornito.
Codice proprio di gh: gh non è riuscito dopo l'autenticazione (rete, limite di richieste, issue disabilitate). La CLI ristampa prima il tuo feedback e l'URL di invio manuale.

openspec completion

Installa o genera completamenti per la shell.

bash

openspec completion install        # rileva la tua shell, installa, configura
openspec completion generate zsh   # stampa lo script su stdout

Shell supportate: zsh, bash, fish, powershell. Ogni sottocomando accetta un argomento shell opzionale. Se lo ometti, la CLI rileva la tua shell dall'ambiente.

Sottocomando	Cosa fa
`generate [shell]`	Stampa lo script di completamento su stdout.
`install [shell]`	Scrive lo script e configura il tuo file di avvio della shell.
`uninstall [shell]`	Rimuove lo script e il blocco di configurazione.

Installato con Nix, i completamenti sono già presenti: il pacchetto flake include gli script Bash, Fish e Zsh nelle posizioni standard, quindi install non è necessario (Installazione).

openspec completion generate

Stampa lo script e non scrive nulla.

#compdef openspec

# Script di completamento Zsh per la CLI OpenSpec
# Generato automaticamente - non modificare manualmente

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

openspec completion install

Scrive lo script e modifica la configurazione della tua shell. Le modifiche alla configurazione si trovano tra i marcatori # OPENSPEC:START e # OPENSPEC:END. Uno script esistente viene prima sottoposto a backup (copia .backup-<timestamp>).

Shell	Posizione dello script	Configurazione modificata
zsh	`~/.zsh/completions/_openspec`	`$ZDOTDIR/.zshrc` quando `ZDOTDIR` è un percorso assoluto, altrimenti `~/.zshrc`
bash	`~/.local/share/bash-completion/completions/openspec`	`~/.bashrc`
fish	`~/.config/fish/completions/openspec.fish`	Nessuna: fish lo carica automaticamente.
powershell	`OpenSpecCompletion.ps1` accanto al tuo profilo	`$PROFILE`

Con Oh My Zsh installato, lo script finisce in $ZSH_CUSTOM/completions/_openspec invece (predefinito ~/.oh-my-zsh/custom/completions/_openspec).

Un ZDOTDIR relativo o con prefisso ~ viene ignorato e viene modificato ~/.zshrc invece. Eseguire di nuovo install quando lo script è già aggiornato aggiunge comunque il blocco al .zshrc che zsh legge.

Opzioni

Flag	Effetto
`--verbose`	Stampa anche il percorso installato, eventuale percorso di backup e quale file di configurazione è stato modificato.

Output

✓ Script di completamento installato e .zshrc configurato con successo

Riavvia la shell o esegui: exec zsh

openspec completion uninstall

Rimuove lo script e il blocco di configurazione contrassegnato. Chiede conferma prima di toccare la tua configurazione (predefinito: No).

Per zsh, pulisce il .zshrc che install modifica, e anche ~/.zshrc quando un'installazione precedente ha lasciato un blocco lì sotto ZDOTDIR. Se un blocco non può essere rimosso, uninstall indica il file ed esce con codice 1.

Opzioni

Flag	Effetto
`-y, --yes`	Salta le richieste di conferma.

Output

✓ Script di completamento rimosso da /Users/you/.zsh/completions/_openspec. Configurazione OpenSpec rimossa da ~/.zshrc

Codici di uscita

0: script generato, installato o rimosso. Anche una disinstallazione annullata esce con 0.
1: shell non supportata o non rilevata, oppure un passaggio di installazione o disinstallazione non riuscito.

openspec change

Forma nominale deprecata di show, list e validate. Ogni esecuzione avvisa e indica i comandi con verbo iniziale, poi esegue comunque:

Avviso: I comandi "openspec change ..." sono deprecati. Preferisci i comandi con verbo iniziale (es., "openspec list", "openspec validate --changes").
Avviso: "openspec change list" è deprecato. Usa "openspec list".
add-rate-limit

Deprecato	Usa invece
`openspec change show <nome>`	`openspec show <nome>`
`openspec change list`	`openspec list`
`openspec change validate <nome>`	`openspec validate <nome>` (tutte le modifiche: `openspec validate --changes`)

Le sezioni con verbo iniziale documentano i flag.

openspec spec

Forma nominale deprecata di show, list e validate. Ogni esecuzione avvisa e indica i comandi con verbo iniziale, poi esegue comunque:

Avviso: I comandi "openspec spec ..." sono deprecati. Preferisci i comandi con verbo iniziale (es., "openspec show", "openspec validate --specs").
api

Deprecato	Usa invece
`openspec spec show <id>`	`openspec show <id>`
`openspec spec list`	`openspec list --specs`
`openspec spec validate <id>`	`openspec validate <id>` (tutte le specifiche: `openspec validate --specs`)

Le sezioni con verbo iniziale documentano i flag.

CLI ​

Comandi ​

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 ​

openspec view ​

openspec validate ​

--report full|findings ​

Output testuale dei riscontri ​

Output JSON dei riscontri ​

Richieste di report non valide ​

Filtrare esternamente un report completo ​

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

Comandi

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

openspec view

openspec validate

--report full|findings

Output testuale dei riscontri

Output JSON dei riscontri

Richieste di report non valide

Filtrare esternamente un report completo

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