CLI

Os comandos de terminal do openspec.

Comandos

Configuração

Comando	O que faz
openspec init	Inicializa o OpenSpec em um projeto.
openspec update	Atualiza os arquivos de instrução instalados pelo OpenSpec.
openspec config	Exibe e altera a configuração global.

Mudanças e specs

Comando	O que faz
openspec list	Lista mudanças ou specs com --specs.
openspec show	Exibe uma mudança ou spec, como markdown ou JSON.
openspec view	Painel em uma única tela de specs e mudanças.
openspec validate	Verifica mudanças e specs quanto a problemas estruturais.
openspec archive	Move uma mudança concluída para o arquivo e atualiza as specs principais.

Fluxos de trabalho e schemas

Seu agente executa a maioria destes durante o fluxo de trabalho.

Comando	O que faz
openspec new	Cria um novo diretório de mudança.
openspec status	Status de conclusão dos artefatos de uma mudança ou de todas as mudanças ativas.
openspec instructions	Instruções para criar um artefato, aplicar ou arquivar.
openspec templates	Caminhos de template resolvidos para os artefatos de um schema.
openspec schemas	Lista os schemas de fluxo de trabalho disponíveis.
openspec schema	Inspeciona, faz fork ou cria um schema (experimental).

Multi-repo (beta)

Comando	O que faz
openspec store	Cria e gerencia stores: repositórios OpenSpec independentes registrados na sua máquina.
openspec doctor	Informa a integridade dos relacionamentos da raiz OpenSpec resolvida.
openspec context	Exibe o contexto de trabalho da raiz OpenSpec resolvida.
openspec workset	Compõe, mantém e abre visualizações de trabalho pessoais.

Utilitários

Comando	O que faz
openspec version	Informa a versão instalada e, opcionalmente, verifica se há uma atualização.
openspec install	Instala o openspec standalone, que funciona sem Node.js.
openspec feedback	Envia feedback sobre o OpenSpec.
openspec completion	Instala ou gera completions de shell.

Obsoletos

Comando	O que faz
openspec change	Forma nominal de show, list e validate para mudanças. A CLI avisa e indica os comandos iniciados por verbo.
openspec spec	Forma nominal de show, list e validate para specs, com o mesmo aviso.

Todos os comandos aceitam -h, --help. O comando openspec sem argumentos também aceita:

• -V, --version: exibe a versão da CLI.
• --no-color: desativa a saída colorida.

openspec init

Inicializa o OpenSpec em um projeto.

openspec init                        # diretório atual, seletor interativo de ferramentas
openspec init --tools claude,cursor  # configura ferramentas específicas, sem prompts
openspec init --tools none           # apenas estrutura openspec/, sem arquivos de ferramentas

Sem --tools, o init solicita que você escolha ferramentas em um terminal interativo. Fora dele, ele configura as ferramentas que detecta no projeto. Se nenhuma for detectada, ele sai com código 1 e lista os IDs válidos.

Repositórios somente de armazenamento

Quando openspec/config.yaml contém uma linha store: e o repositório não tem especificações ou alterações locais, execute o init a partir da raiz do repositório:

# instala os arquivos de integração do Claude Code no repositório de código
openspec init --tools claude

• Arquivos de integração: gravados no repositório de código.
• openspec/config.yaml: preservado byte a byte.
• openspec/specs/ e openspec/changes/: não criados no repositório de código.

Executar o init a partir de um subdiretório sai com código 1 e informa que você deve executá-lo a partir da raiz do repositório. --language também sai com código 1, porque o idioma pertence à configuração do store externo. Execute o init na raiz do store ou edite essa configuração diretamente.

Argumentos

Argumento	O que é
path	O diretório do projeto a inicializar. Padrão: diretório atual. Criado se não existir.

Opções

Opção	Efeito
--tools <tools>	IDs de ferramentas separados por vírgula, all ou none. Pula o seletor. Os IDs estão listados em Ferramentas suportadas.
--language <language>	Adiciona uma instrução de idioma a uma nova configuração de projeto. Rejeitado quando a linha store: do repositório aponta para um store externo.
--force	Remove arquivos de layouts antigos do OpenSpec sem perguntar. Execuções interativas, caso contrário, confirmam a limpeza primeiro.
--profile <profile>	Substitui o perfil de configuração global para esta execução: core (o conjunto de fluxos de trabalho padrão) ou custom (os fluxos de trabalho salvos na configuração global).
--no-animation	Mostra uma tela de boas-vindas estática em vez da animada.

Saída

Cada ferramenta selecionada recebe as habilidades e comandos do OpenSpec em seu próprio diretório:

▌ 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 cria apenas openspec/config.yaml. Em um projeto já inicializado, o init reescreve os arquivos instalados no lugar e o resumo mostra Refreshed: Claude Code com Config: openspec/config.yaml (exists).

Códigos de saída

• 0: configuração concluída.
• 1: valor inválido de --tools ou --profile, uma execução não interativa sem ferramentas detectadas e sem --tools, ou uma invocação inválida de somente armazenamento.

openspec update

Atualiza os arquivos de instrução instalados do OpenSpec.

openspec update             # atualiza ferramentas cujos arquivos são mais antigos que a CLI
openspec update --force     # reescreve arquivos mesmo quando estão atualizados
openspec update --dry-run   # lista o que uma atualização mudaria, e não muda nada

O update encontra as ferramentas que o init configurou e compara os arquivos gerados com a versão da CLI. Quando existe uma versão mais recente do OpenSpec, ele primeiro oferece atualizar a CLI e depois executa novamente com a versão atualizada. Defina OPENSPEC_NO_UPDATE_CHECK=1 para pular a verificação.

Argumentos

Argumento	O que é
path	O diretório do projeto a atualizar. Padrão: diretório atual.

Opções

Opção	Efeito
--force	Reescreve os arquivos de todas as ferramentas configuradas, mesmo quando estão atualizados.
--dry-run	Relata cada arquivo que a atualização adicionaria, alteraria ou excluiria, e não grava nada. Sem verificação de atualização da CLI, sem prompts. Combine com --force para visualizar uma atualização forçada.
--json	Com --dry-run, imprime o plano como JSON. Sem --dry-run, sai com código 1.

Visualizando uma atualização

--dry-run planeja a atualização que uma execução não interativa faria: o mesmo caminho de código, com cada gravação e exclusão registrada em vez de executada. Cada arquivo que a atualização real tocaria é listado, incluindo:

• mover arquivos do OpenSpec para fora do diretório anterior de uma ferramenta (.kimi/ para .kimi-code/, .windsurf/ para .devin/, .codex/ e .agent/ para .agents/);
• salvar a configuração global quando uma instalação anterior aos perfis recebe uma;
• sincronizar os arquivos do agente de nuvem do GitHub Copilot;
• com --force, configurar ferramentas encontradas apenas em artefatos legados e limpar esses artefatos, incluindo prompts globais aposentados do Codex.

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 imprime o mesmo plano como um documento 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	O que contém
changes[].path	Caminho relativo ao projeto. Um arquivo fora do projeto, como uma habilidade global ou a configuração global, é mostrado a partir do seu diretório inicial como ~/..., ou como um caminho absoluto quando também está fora do diretório inicial.
changes[].action	add, update ou delete. Um arquivo cujos novos bytes coincidem com os antigos não é listado.
changes[].tool	A ferramenta configurada à qual o arquivo pertence, como claude. Arquivos que pertencem ao próprio OpenSpec em vez de uma ferramenta, a configuração global e a limpeza de artefatos legados, são openspec.
notes[]	{ code, message } para uma etapa sobre a qual um usuário de terminal seria questionado. legacy-tool-directories: uma movimentação que uma execução interativa pergunta primeiro; changes a lista como feita. legacy-artifacts: arquivos do layout antigo do OpenSpec foram encontrados, como comandos de barra openspec-proposal.md ou blocos de marcadores do OpenSpec em AGENTS.md. Sem --force, uma atualização não interativa os deixa em paz, então changes também; --dry-run --force lista a limpeza deles. Vazio para uma atualização comum.
failures[]	{ tool, error } para cada ferramenta em que a atualização real falharia, incluindo uma gravação que ela não pode fazer: um diretório onde um arquivo pertence, um arquivo onde um diretório pertence, ou um arquivo ou pasta sem permissão de gravação. Para essa ferramenta, changes para onde a atualização real para; as outras ferramentas ainda são planejadas. Falhas que o disco só relata durante a gravação, como falta de espaço, não podem ser previstas.

Uma falha antes do planejamento, como nenhum diretório do OpenSpec, ainda imprime exatamente um documento JSON: o plano vazio mais uma matriz status com severity, code (update_error) e message. O código de saída é 1.

Saída

Quando os arquivos de todas as ferramentas correspondem à versão da CLI:

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

Use --force to refresh files anyway.

Quando os arquivos de uma ferramenta vieram de uma CLI mais antiga (ou com --force, que imprime Force updating 1 tool(s): claude em vez disso):

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.

Em um diretório sem OpenSpec, o update recusa:

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

Códigos de saída

• 0: arquivos atualizados, ou tudo já está atualizado.
• 1: nenhum diretório do OpenSpec no caminho, ou a atualização falhou.

openspec config

Visualiza e altera a configuração global.

openspec config list                  # vê as configurações atuais
openspec config set delivery skills   # altera um valor
openspec config profile               # seletor interativo de fluxos de trabalho

Subcomando	O que faz
path	Imprime a localização do arquivo de configuração.
list	Mostra todas as configurações atuais.
get <key>	Imprime um valor, bruto e utilizável em scripts.
set <key> <value>	Define um valor, coagindo seu tipo.
unset <key>	Remove uma chave para que seu padrão seja aplicado.
reset	Redefine toda a configuração para os padrões.
edit	Abre o arquivo de configuração em $EDITOR.
profile [preset]	Configura o modo de entrega e os fluxos de trabalho.

A configuração é global para sua máquina, armazenada como JSON onde config path aponta: $XDG_CONFIG_HOME/openspec/config.json se definido, caso contrário ~/.config/openspec/config.json (macOS, Linux) ou %APPDATA%\openspec\config.json (Windows). Cada subcomando aceita --scope <scope>, mas apenas global funciona hoje. Qualquer outro escopo sai com código 1 e Error: Project-local config is not yet implemented.

openspec config path

openspec config path

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

openspec config list

openspec config list          # configurações legíveis mais resumo do perfil
openspec config list --json   # configuração bruta como JSON

Opções

Opção	Efeito
--json	Imprime o objeto de configuração como JSON.

Saída

Cada configuração, depois um resumo do perfil que marca valores como explícitos ou padrão:

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

openspec config get delivery

Argumentos

Argumento	O que é
key	A chave a ler. Pontos alcançam valores aninhados (featureFlags.workspaces).

Saída

O valor puro, pronto para scripts. Objetos são impressos como JSON compacto:

both

Códigos de saída

• 0: valor impresso.
• 1: a chave não tem valor, e nada é impresso.

openspec config set

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

Argumentos

Argumento	O que é
key	A chave a gravar, com pontos para valores aninhados.
value	O novo valor. true/false tornam-se booleanos, strings numéricas tornam-se números.

Opções

Opção	Efeito
--string	Armazena o valor como string, ignorando a coerção de tipo.
--allow-unknown	Permite chaves que o esquema não conhece.

Saída

Set featureFlags.workspaces = true

Chaves desconhecidas e valores inválidos falham com código 1 antes de qualquer coisa ser salva:

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 o arquivo de configuração existir, mas não contiver um objeto JSON, seja porque não é JSON válido ou porque sua raiz é outra coisa, como null ou uma matriz, config set, config unset e config profile saem com código 1 e deixam o arquivo inalterado. Corrija-o com openspec config edit ou substitua-o com 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".

Até que seja corrigido, a telemetria e a verificação de atualização permanecem desativadas.

openspec config unset

openspec config unset delivery

Remove a chave para que o padrão seja aplicado novamente. Chaves com padrões embutidos sempre contam como definidas, então isso relata sucesso mesmo se você nunca as definiu:

Unset delivery (reverted to default)

Uma chave sem nenhum valor imprime Key "featureFlags.nothere" was not set. Ambos os casos saem com código 0. Um arquivo de configuração que não pode ser analisado sai com código 1, como em config set.

openspec config reset

openspec config reset --all      # pede confirmação
openspec config reset --all -y   # sem prompt

Opções

Opção	Efeito
--all	Obrigatório. Redefine tudo.
-y, --yes	Pula o prompt de confirmação.

Saída

Configuration reset to defaults

Sem --all, sai com código 1 e imprime a linha de uso.

Códigos de saída

• 0: redefinição concluída, ou você respondeu não no prompt.
• 1: --all ausente.
• 130: prompt cancelado com Ctrl-C.

openspec config edit

openspec config edit

Abre o arquivo de configuração em $EDITOR (recorrendo a $VISUAL), criando-o primeiro com os padrões se não existir. Quando o editor fecha, o arquivo é validado. JSON inválido ou configuração inválida sai com código 1.

O valor do editor pode conter argumentos e caminhos entre aspas, por exemplo code --wait ou "/Applications/Sublime Text.app/Contents/SharedSupport/bin/subl" -w. Ele é dividido em palavras sem um shell, então $VAR, ~ e ; são repassados literalmente. Um editor que não pode iniciar, ou que sai com código diferente de zero, imprime um erro de uma linha e sai com código 1.

Sem editor configurado, sai com código 1:

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

openspec config profile

openspec config profile        # seletor interativo (precisa de terminal)
openspec config profile core   # aplica a predefinição core diretamente

Argumentos

Argumento	O que é
preset	Nome opcional de predefinição. Apenas core existe. Ele seleciona os fluxos de trabalho principais e mantém sua configuração de entrega.

Sem predefinição, um seletor interativo mostra sua entrega e fluxos de trabalho atuais, permite alterar um ou ambos (entrega: ambos, apenas habilidades ou apenas comandos; fluxos de trabalho: uma lista de caixas de seleção), imprime a diferença e, dentro de um projeto OpenSpec, oferece executar openspec update para você. Fora de um terminal, sai com código 1:

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

Saída

A configuração alterada não alcança os projetos até que eles atualizem:

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

Códigos de saída

• 0: perfil salvo, ou você manteve as configurações atuais.
• 1: predefinição desconhecida, sem terminal, ou o openspec update oferecido falhou.
• 130: seletor cancelado com Ctrl-C.

openspec list

Lista mudanças ou, com --specs, especificações.

openspec list                    # mudanças ativas, mais recentemente modificadas primeiro
openspec list --archived         # mudanças arquivadas
openspec list --all              # mudanças ativas e arquivadas
openspec list --specs            # especificações com contagens de requisitos
openspec list --json             # legível por máquina, inclui a raiz resolvida

As linhas vêm de openspec/changes/ e openspec/specs/ sob a raiz resolvida. A listagem padrão de mudanças ignora openspec/changes/archive/.

Opções

Opção	Efeito
--specs	Lista especificações em vez de mudanças.
--changes	Lista mudanças. Este é o padrão.
--archived	Lista apenas mudanças arquivadas. Não pode ser combinado com --specs.
--all	Lista mudanças ativas e arquivadas. Não pode ser combinado com --specs. Tem precedência sobre --archived.
--sort <order>	recent (última modificação primeiro) ou name. Padrão: recent. As especificações sempre são ordenadas por nome.
--json	Imprime JSON em vez da tabela.
--store <id>	Usa um store registrado como a raiz do OpenSpec em vez do projeto atual.

Saída

Uma linha por mudança: nome, status das tarefas, última modificação. A coluna de status exibe No tasks, 2/5 tasks ou ✓ Complete.

Changes:
  add-rate-limit     No tasks      just now

--all agrupa mudanças ativas e arquivadas sob títulos separados. Cada grupo usa a ordem de classificação selecionada:

Changes:
  add-rate-limit     No tasks      just now

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

Specs:
  api     requirements 1

--json adiciona contagens de tarefas e um status de no-tasks, in-progress ou complete:

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

Com --archived ou --all, cada objeto de mudança inclui um booleano archived. O array combinado usa a ordem de classificação selecionada. Uma mudança arquivada ainda pode ter status in-progress quando seu arquivo de tarefas rastreado tem tarefas não marcadas. Sem qualquer uma dessas opções, a estrutura do JSON permanece inalterada.

Uma listagem vazia imprime No active changes found., No archived changes found., No changes found. ou No specs found. e ainda termina com código 0.

Uma mudança é um diretório diretamente sob openspec/changes/. Diferentemente das especificações, mudanças não podem ser aninhadas em uma pasta de namespace. Uma pasta como changes/mobile/ que apenas encapsula uma mudança (changes/mobile/refresh-token/) é listada com o status not a change, seguida por um aviso que nomeia os diretórios aninhados. --json marca essa entrada com um array nested e adiciona um array warnings de nível superior. show, status, validate e archive recusam a pasta com a mesma mensagem. Para corrigir isso, mova a mudança para cima e incorpore o namespace ao nome dela:

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

Códigos de saída

• 0: listagem exibida, mesmo quando vazia.
• 1: nenhuma raiz do OpenSpec encontrada (fora de um projeto, sem --store).

openspec show

Imprime uma mudança ou especificação, como markdown ou JSON.

openspec show add-rate-limit              # mudança: imprime proposal.md
openspec show add-rate-limit --diff       # mudança: anexa diffs de requisito
openspec show api                         # especificação: imprime spec.md
openspec show api --json --no-scenarios   # JSON de especificação sem o texto do cenário

Sem um nome, o comando show pergunta se você quer uma mudança ou uma especificação e, em seguida, lista itens para escolher. Fora de um terminal interativo, ele termina com código 1 e imprime as formas diretas em vez disso.

Argumentos

Argumento	O que é
item-name	A mudança ou especificação a exibir, pelo nome da pasta (add-rate-limit, api).

Opções

Opção	Efeito
--json	Imprime JSON estruturado em vez de markdown bruto.
--type <change|spec>	Escolhe o tipo quando uma mudança e uma especificação compartilham um nome.
--no-interactive	Nunca solicita entrada: um nome ausente se torna um erro.
--deltas-only	JSON, mudança: restringe a saída a deltas. O JSON de mudança já contém apenas deltas, então a saída é igual à de --json simples.
--requirements-only	Alias obsoleto de --deltas-only. Emite aviso em stderr.
--diff	Mudança: anexa diffs de delta por requisito. Ignorado com um aviso para especificações.
--requirements	JSON, especificação: mantém o texto do requisito, esvazia os arrays scenarios.
--no-scenarios	JSON, especificação: mesma saída que --requirements.
-r, --requirement <id>	JSON, especificação: exibe um requisito pela posição baseada em 1. Não pode ser combinado com --requirements.
--store <id>	Usa um store registrado como a raiz do OpenSpec em vez do projeto atual.

Opções que não se aplicam ao tipo resolvido são ignoradas com um aviso em stderr.

Saída

O modo texto é uma passagem direta do conteúdo bruto: uma mudança exibe seu proposal.md, uma especificação exibe seu spec.md.

# Add rate limiting

Por que

Clientes não autenticados podem esgotar a API.

O que muda

• Adicionar limitação de taxa por cliente à API pública.

Para uma alteração, `--diff` imprime a proposta primeiro, depois uma seção `Specifications Changed (diffs)`. Requisitos ADDED incluem seu texto completo. Requisitos REMOVED mantêm a Reason e Migration autoradas. Requisitos RENAMED mostram FROM e TO. Requisitos MODIFIED mostram um diff unificado em relação ao requisito principal correspondente.

Se um cabeçalho MODIFIED corresponder apenas após normalização de maiúsculas/minúsculas ou espaços em branco, a saída inclui tanto o diff quanto um aviso de que a correspondência de arquivo é exata. Se a spec principal ou o requisito estiver ausente, a saída emite um aviso e imprime o bloco delta completo. Um bloco MODIFIED sem diferença textual imprime `(no textual changes)`.

Uma alteração com `--json` tem formato 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"
  }
}

Cada requisito carrega seu name, o texto do cabeçalho após Requirement:. Este é o nome pel qual o arquivo corresponde entradas MODIFIED, REMOVED e RENAMED. Cada cenário carrega seu name, o texto do cabeçalho após Scenario:. Um # de fechamento em qualquer um dos cabeçalhos não faz parte do nome.

--json --diff mantém essa forma de nível superior. Um delta MODIFIED ganha uma string diff, uma string warning, ou ambas. Outras operações permanecem inalteradas. Uma string diff vazia significa que os blocos principal e delta são textualmente idênticos.

Uma spec com --json lista seus requisitos com cenários. Requisitos e cenários carregam os mesmos campos name do JSON de alteração:

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

Um nome desconhecido sugere correspondências próximas: Unknown item 'does-not-exist'. Did you mean: add-rate-limit, api?. Um nome que corresponde tanto a uma alteração quanto a uma spec gera erro e solicita --type.

Códigos de saída

• 0: item impresso.
• 1: nome desconhecido ou ambíguo, nenhum nome fora de um terminal, um índice -r fora do intervalo, --requirements combinado com -r, ou um delta ou spec principal que não pode ser lido para --diff.

openspec view

Imprime um painel de uma tela de specs e alterações.

openspec view   # resumo do projeto em uma tela

view imprime o painel uma vez e sai. Ele não lê nenhuma tecla. Alterações são agrupadas por progresso de tarefas: Draft (nenhuma tarefa ainda), Active (tarefas em andamento, com barra de progresso e percentual), Completed (todas as tarefas marcadas). Specs são listadas com contagem de requisitos, da maior para a menor.

Opções

Flag	Efeito
--store <id>	Usar um repositório registrado como raiz do OpenSpec em vez do projeto atual.

Saída

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 ou openspec list --specs para visualizações detalhadas

Uma linha de resumo Task Progress aparece quando alguma alteração tem tarefas em andamento.

Cada alteração ativa também mostra seus estados de schema e artefato abaixo da barra de progresso de tarefas:

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

Marcador	Estado do artefato
✓	Sua saída existe. Um artefato de tarefas existente é considerado concluído mesmo quando sua checklist não está finalizada.
→	Está pronto para ser criado.
Sem marcador	Está bloqueado por uma dependência ausente.
(skipped)	A alteração o ignora.

Se um workflow não puder ser carregado, view imprime um aviso e mantém visível o progresso de tarefas dessa alteração. Execute openspec status --change <name> para inspecionar o workflow separadamente. Após openspec view --store <id>, passe o mesmo --store <id> para status.

Códigos de saída

• 0: painel impresso.
• 1: nenhuma raiz OpenSpec encontrada (fora de um projeto, sem --store).

openspec validate

Verifica alterações e specs quanto a problemas estruturais.

openspec validate add-rate-limit   # uma alteração ou spec, por nome
openspec validate --all            # todas as alterações e specs

Sem nome e sem flag de verificação em massa, validate solicita que você escolha itens. Fora de um terminal interativo, ele sai com código 1 e imprime as flags de verificação em massa.

Argumentos

Argumento	O que é
item-name	A alteração ou spec a ser validada, por nome da pasta (add-rate-limit, api).

Opções

Flag	Efeito
--all	Validar todas as alterações e specs.
--changes	Validar todas as alterações.
--specs	Validar todas as specs.
--archived	Verificar conclusão de tarefas em alterações arquivadas, sem validar seus deltas de spec aplicados.
--strict	Tratar avisos como falhas.
--type <change|spec>	Escolher o tipo quando uma alteração e uma spec compartilham o mesmo nome.
--json	Imprimir um relatório estruturado em vez de texto.
--report <mode>	Saída em massa: full (padrão) ou findings. Requer um escopo de verificação em massa explícito.
--concurrency <n>	Máximo de validações paralelas em execuções em massa. Padrão: OPENSPEC_CONCURRENCY, senão 6.
--no-interactive	Nunca solicitar: um nome ausente ou ambíguo se torna um erro.
--store <id>	Usar um repositório registrado como raiz do OpenSpec em vez do projeto atual.

Saída

Execuções em massa imprimem uma linha de status por item, seguida de quaisquer descobertas, e terminam com totais:

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

Descobertas de checkbox de tarefas

Contagens de progresso verificam checkboxes e nada mais, então um arquivo de tarefas escrito como marcadores simples é lido como zero tarefas: openspec list e openspec status reportam nenhum trabalho, e openspec archive não tem nada a sinalizar como incompleto. Validate reporta um WARNING em cada arquivo de tarefas rastreado que lista trabalho sem checkbox:

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

O aviso é emitido apenas quando todo o conjunto rastreado da alteração não contém nenhum checkbox. Um arquivo de prosa ao lado de uma checklist real não é reportado, e uma alteração em meio à autoria mantém seu progresso no momento em que existe um único checkbox. --strict transforma o aviso em falha. O número da linha está no relatório --json.

Blocos cercados, comentários HTML, front matter YAML e código indentado não são verificados, então uma amostra de terminal colada nunca é confundida com uma lista de tarefas.

Descobertas de mesclagem de arquivo

Para alterações, validate executa o construtor de mesclagem do arquivo contra as specs principais atuais sem gravar arquivos. Ele reporta conflitos de mesclagem, como um alvo MODIFIED ausente ou um requisito ADDED conflitante, como INFO:

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

Essas descobertas aparecem mesmo quando a validação passa, tanto na saída de texto quanto na JSON. INFO nunca altera o código de saída, inclusive sob --strict: um alvo ausente pode pertencer a uma alteração irmã que ainda não foi arquivada. Deltas já sincronizados nas specs principais seguem as regras de mesclagem existentes do arquivo.

Essa verificação não executa a validação posterior de spec mesclada do arquivo nem as verificações de aposentadoria. Um relatório limpo não garante que o arquivo será bem-sucedido.

Se a pré-verificação de mesclagem não puder ser iniciada, uma descoberta INFO explica o motivo. As descobertas de validação existentes e o código de saída permanecem inalterados.

Um item com falha lista cada problema e a correção:

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 imprime um relatório para a execução:

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

Entradas em issues carregam um level de ERROR, WARNING ou INFO.

Códigos de saída

• 0: todos os itens validados passaram, incluindo um escopo de verificação em massa vazio.
• 1: um item falhou, a solicitação de relatório é inválida, openspec/config.yaml não pode ser lido ou não é YAML válido, ou a execução falhou (por exemplo, um nome desconhecido ou nenhuma raiz OpenSpec). Uma configuração que não pode ser lida ou analisada interrompe a execução antes de qualquer item ser verificado; com --json é reportada como uma única entrada status com o código unreadable_config ou unparseable_config.

--report full|findings

Seleciona a saída para um escopo de validação em massa explícito:

• full: todos os itens. Este é o padrão. --report full explícito mantém a forma de saída existente sem adicionar metadados de relatório.
• findings: apenas itens com problemas, incluindo itens aprovados com avisos ou informações. Todos os itens ainda são validados. Totais, comportamento do modo estrito e códigos de saída permanecem inalterados.

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

Escopos

Flags	report.scope de findings
--all	all
--changes	changes
--specs	specs
--changes --specs, ou --all com qualquer uma das flags	all
--archived	archived

Ambos os modos de relatório explícitos rejeitam um nome de item posicional, um escopo de verificação em massa ausente, ou escopos de arquivo e ativos combinados.

Saída de texto de findings

Saída humana: stdout imprime Scope: <scope> (<count> items), depois os totais. Sem itens com problemas:

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

Rótulos de itens com problemas, rótulos de severidade, caminhos e mensagens são impressos em stderr. Falhas de escopo ativo mantêm a dica de nova execução Details: após os totais. O banner de raiz e a saída de progresso existentes podem preceder o relatório.

Saída JSON de findings

--report findings --json imprime um documento. Este exemplo tem dois itens limpos:

{
  "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: identificam a forma validation-findings, versão 1.0. Não há version ou items de nível superior.
• report.returnedItems e report.totalItems: contam os registros retornados e todos os itens validados, respectivamente.
• itemFindings: registros completos de itens cujo array issues não está vazio. Inclui issues ERROR, WARNING e INFO. Cada registro mantém id, type, valid, issues e durationMs. Itens arquivados usam type: "change".
• summary: totais da execução completa e contagens por tipo, não contagens do subconjunto retornado. Um escopo vazio tem totais zero e sai com código 0.
• root: os mesmos metadados de raiz selecionada que o relatório completo.

Preservação de registros: itens retornados mantêm sua ordem do relatório completo e quaisquer campos aditivos em itens ou issues. A filtragem não reescreve mensagens ou locais, incluindo campos opcionais line e column.

Falhas de comando: falhas de seleção de raiz ou descoberta de itens mantêm o diagnóstico status existente e saem com código 1. Elas não retornam um relatório de findings concluído ou um relatório vazio bem-sucedido.

Solicitações de relatório inválidas

Ambos os modos de relatório explícitos rejeitam essas solicitações antes da seleção de raiz ou descoberta de itens:

• Um valor de relatório não suportado, incluindo uma string vazia.
• Um nome de item posicional, mesmo com uma flag de verificação em massa.
• Nenhum escopo de verificação em massa explícito.
• --archived combinado com --all, --changes ou --specs.

No modo JSON, uma solicitação rejeitada sai com código 1 com apenas um array status de elemento único. Não tem root nem payload de relatório:

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

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

O modo humano imprime o erro em stderr. Um --report isolado sem valor é um erro de sintaxe do Commander em stderr, inclusive com --json; ele não usa este envelope de diagnóstico.

Filtrar um relatório completo externamente

Para uma visualização JSON personalizada, filtre o relatório completo com jq ou PowerShell. Estes exemplos de script preservam o código de saída da validação e deixam documentos de erro de comando intactos.

Em Bash com jq:

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

Em 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

Essas visualizações personalizadas mantêm as chaves do relatório completo, mas omitem itens limpos. Elas não são relatórios completos full-v1 nem a forma versionada --report findings.

openspec archive

Move uma change concluída para o archive e atualiza as specs principais.

openspec archive add-rate-limit -y                # arquiva uma change, mescla seus deltas
openspec archive add-rate-limit -y --skip-specs   # arquiva sem tocar nas specs

Sem um nome, o archive solicita que você escolha uma change. Fora de um terminal interativo, ele encerra com código 1 e, em vez disso, imprime o comando para executar novamente.

Argumentos

Argumento	O que é
change-name	A change a ser arquivada, pelo nome da pasta (add-rate-limit).

Opções

Flag	Efeito
-y, --yes	Responde sim a todas as confirmações: atualizações de specs, tarefas incompletas, validação ignorada.
--skip-specs	Arquiva sem tocar nas specs principais (mudanças de infraestrutura, ferramentas ou apenas de documentação).
--no-validate	Ignora a validação. O archive pede que você confirme primeiro, e -y responde por você.
--json	Imprime um resultado estruturado em vez de texto. Requer --yes para confirmar as atualizações de specs.
--store <id>	Usa um store registrado como raiz do OpenSpec em vez do projeto atual.

Saída

Uma execução bem-sucedida informa o status das tarefas, pré-visualiza as atualizações de specs, aplica-as e informa o nome da pasta de archive:

Task status: ✓ Complete

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

A pasta da change é movida por inteiro para openspec/changes/archive/2026-08-11-add-rate-limit/, com a data de hoje prefixada ao seu nome. Cada delta é mesclado em sua spec principal: o requisito ADDED acima foi anexado a openspec/specs/api/spec.md. Sem -y, o archive mostra a pré-visualização e pergunta antes de atualizar. Ao recusar, a change ainda é arquivada e as specs permanecem inalteradas.

Com --json --yes:

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

O archive valida a change primeiro e recusa uma que falhe:

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.

Tarefas incompletas emitem avisos, mas não bloqueiam. No modo interativo, o archive pergunta se deve continuar, e -y continua por conta própria:

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

Códigos de saída

• 0: a change foi arquivada, com ou sem atualizações de specs.
• 1: a validação falhou, o nome da change é desconhecido, ou uma confirmação era necessária e nenhuma resposta pôde ser lida.

openspec new

Cria um novo diretório de change.

openspec new change add-caching                                # apenas metadados
openspec new change add-search --goal "Users can search docs"  # registra um objetivo

new tem um subcomando, new change <name>. Ele cria openspec/changes/<name>/ contendo um único arquivo de metadados .openspec.yaml:

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

Os artefatos (proposta, specs, design, tarefas) não são gerados aqui. Você os escreve depois, e o openspec status informa qual é o próximo.

Argumentos

Argumento	O que é
name	Nome da pasta para a change (add-caching).

Opções

Flag	Efeito
--description <text>	Também cria um README.md no diretório da change com esse texto.
--goal <text>	Armazena uma linha goal: em .openspec.yaml.
--schema <name>	Esquema de fluxo de trabalho para a change. Padrão: spec-driven, o único esquema que acompanha a ferramenta.
--json	Imprime a change criada como JSON em vez de texto.
--store <id>	Usa um store registrado como raiz do OpenSpec em vez do projeto atual.

Saída

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

Quando nenhum diretório openspec/ é encontrado, o new change cria um onde você está e informa isso:

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.

O aviso vai para o stdout junto com o restante da saída legível por humanos, e nunca aparece com --json.

Com --json, em um projeto que já possui openspec/:

{
  "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 nenhum diretório openspec/ é encontrado e o new change cria um, o JSON tem a mesma forma. root.path é o diretório de onde você executou o comando, e root.source aparece como implicit:

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

Códigos de saída

• 0: change criada.
• 1: a change já existe, ou o esquema é desconhecido.

openspec status

Relata o status de conclusão dos artefatos de uma alteração ou de todas as alterações ativas.

openspec status --change add-rate-limit          # visualização de checklist
openspec status --change add-rate-limit --json   # relatório estruturado
openspec status --all                            # todas as alterações ativas
openspec status --all --json                     # um relatório em lote

Quando houver alterações ativas, use exatamente uma entre --change e --all. Sem nenhuma delas, o status encerra com código 1 e lista as alterações disponíveis, mesmo quando só existe uma:

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

Quando o projeto não tem alterações ativas, o status imprime No active changes. Create one with: openspec new change <name> e encerra com código 0 mesmo sem nenhuma das opções. Com --all --json, o mesmo estado vazio é { "changes": [], "message": "No active changes.", "root": ... }.

Opções

Opção	Efeito
--change <id>	A alteração a ser relatada, pelo nome da pasta.
--all	Relata todas as alterações ativas, ordenadas por nome. Não pode ser combinada com --change.
--schema <name>	Substitui o schema detectado automaticamente em openspec/config.yaml. Um nome desconhecido é um erro.
--json	Imprime um relatório estruturado em vez de texto.
--store <id>	Use um store registrado como raiz do OpenSpec em vez do projeto atual.

Saída

Uma checklist dos artefatos do schema: [x] concluído, [ ] pronto para escrever, [-] bloqueado até que os artefatos dos quais depende existam.

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

A linha Next: indica o único comando que faz a alteração avançar, então openspec status basta para retomar uma alteração em uma nova sessão. Ela indica o próximo artefato pronto enquanto o planejamento não estiver concluído, e openspec instructions apply quando todos os artefatos de planejamento existirem:

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

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

Ela inclui --store <id> sempre que a raiz resolvida for um store, e indica o mesmo comando que a frase nextSteps do JSON.

--json adiciona dependências por artefato, caminhos de arquivo resolvidos e uma próxima etapa sugerida. Resumido:

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

Com --all --json, changes contém o mesmo objeto de status para cada alteração, sem um root por alteração. A raiz selecionada aparece uma vez no envelope. Este exemplo omite os campos de status por alteração mostrados acima:

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

Se uma alteração não puder ser carregada, o lote continua. Sua entrada contém changeName e um diagnóstico em status, enquanto as demais entradas permanecem disponíveis. O comando encerra com código 1, inclusive no modo JSON, para que a CI não aceite um relatório incompleto como bem-sucedido. A saída JSON continua sendo um único documento analisável.

Códigos de saída

• 0: todos os status solicitados foram impressos; um relatório --all vazio também encerra com código 0.
• 1: uma alteração solicitada falhou ao carregar, --change ou --all está ausente, as duas opções foram combinadas, a alteração não existe ou a substituição de schema é desconhecida.

openspec instructions

Imprime instruções para criar um artefato, aplicar ou arquivar. Seu agente executa isto durante o fluxo de trabalho para buscar o texto de instrução para sua próxima etapa.

openspec instructions proposal --change add-rate-limit   # como escrever um artefato
openspec instructions apply --change add-rate-limit      # como implementar a alteração
openspec instructions archive --change add-rate-limit    # entradas para arquivar

Argumentos

Argumento	O que é
artifact	Um id de artefato do schema (proposal, specs, design, tasks em spec-driven), ou as palavras reservadas apply e archive.

Opções

Opção	Efeito
--change <id>	A alteração para a qual gerar instruções. Obrigatório.
--schema <name>	Substitui o schema. Caso contrário, é detectado automaticamente em config.yaml.
--json	Imprime um objeto estruturado em vez de texto.
--store <id>	Use um store registrado como raiz do OpenSpec em vez do projeto atual.

Saída

O formato de artefato imprime um bloco de instrução: a tarefa, o arquivo a escrever, como escrevê-lo, o template do artefato e o que a conclusão dele desbloqueia.

<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 imprime arquivos de contexto, progresso das tarefas e a instrução de trabalho:

## 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 artefatos obrigatórios estiverem ausentes, apply relata ### ⚠️ Blocked e os nomeia em vez disso. archive imprime o nome da alteração, além de qualquer contexto de projeto e orientação de operação da configuração. Quando nada está configurado, ele diz isso e nada mais.

Com --json, cada formato retorna um objeto. O formato de artefato começa:

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

e continua com outputPath, existingOutputPaths, as strings completas instruction e template, dependencies, unlocks e root. O formato apply inclui contextFiles, progress, tasks, taskTrackingConfigured, state (blocked, ready, all_done) e instruction.

Cada entrada de tasks contém id, description, done, sourcePath e line. sourcePath é o caminho absoluto para o arquivo rastreado que forneceu a tarefa. line é o número da linha, começando em 1, da checkbox da tarefa nesse arquivo.

taskTrackingConfigured é sempre um booleano: true quando o schema define um apply.tracks não nulo, mesmo que nenhum arquivo corresponda, e false caso contrário. Se um arquivo de rastreamento correspondente não puder ser lido, unavailableTrackingFiles contém seu path absoluto e o reason do erro. Este campo é omitido quando todos os arquivos correspondentes são legíveis. Arquivos legíveis ainda contribuem para tasks e progress, mas state não pode ser all_done até que todos os arquivos correspondentes sejam lidos.

Códigos de saída

• 0: instruções impressas.
• 1: artefato desconhecido, alteração desconhecida, schema desconhecido ou --change ausente. Cada erro lista os valores válidos.

openspec templates

Exibe os caminhos de template resolvidos para os artefatos de um schema.

openspec templates          # schema padrão: spec-driven
openspec templates --json   # mapa de IDs de artefato para caminhos

Opções

Flag	Efeito
--schema <name>	Schema a ser resolvido. Padrão: spec-driven.
--json	Exibe um mapa JSON de IDs de artefato para caminhos de template.

Saída

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 de onde o schema foi resolvido: project (openspec/schemas/ no seu projeto), user (uma substituição global) ou package (integrado à CLI). Projeto prevalece sobre usuário, usuário sobre pacote.

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

Códigos de saída

• 0: caminhos exibidos.
• 1: schema desconhecido. O erro lista os schemas disponíveis.

openspec schemas

Lista os schemas de fluxo de trabalho disponíveis.

openspec schemas          # nomes, descrições, ordem dos artefatos
openspec schemas --json   # legível por máquina, para uso por agentes

Opções

Flag	Efeito
--json	Exibe como JSON (para uso por agentes).

Saída

Available schemas:

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

Schemas do seu projeto são rotulados como (project), e substituições globais são rotuladas como (user override).

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

Códigos de saída

• 0: schemas listados.
• 1: não foi possível ler a lista de schemas.

openspec schema

Inspeciona, bifurca ou cria um esquema (experimental). Cada subcomando primeiro imprime Note: Schema commands are experimental and may change. no stderr.

openspec schema which spec-driven          # de onde um esquema é resolvido
openspec schema fork spec-driven my-flow   # copia um esquema para o projeto
openspec schema init my-schema             # cria um esquema do zero

Subcomando	O que faz
which	Mostra de onde um esquema é resolvido.
validate	Verifica a estrutura e os modelos de um esquema.
fork	Copia um esquema existente para o projeto para personalização.
init	Cria um novo esquema local ao projeto.

Os esquemas são resolvidos de três locais. A primeira correspondência vence:

Origem	Localização
project	openspec/schemas/ no projeto atual.
user	~/.local/share/openspec/schemas/ (XDG_DATA_HOME e %LOCALAPPDATA% do Windows são respeitados).
package	Os esquemas enviados com a CLI. spec-driven fica aqui.

openspec schema which

Mostra qual cópia de um esquema a CLI usará.

openspec schema which spec-driven
openspec schema which --all        # todos os esquemas, agrupados por origem

Argumentos

Argumento	O que é
name	O esquema a ser consultado. Obrigatório, a menos que --all seja definido. Sem nenhum dos dois, which sai com código 1.

Opções

Flag	Efeito
--all	Lista todos os esquemas com sua origem de resolução.
--json	Imprime a resolução como JSON.

Saída

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

Quando uma cópia de maior prioridade oculta outra, uma seção Shadows: lista as cópias ocultas. Com --json:

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

Um nome desconhecido sai com código 1 e lista os esquemas disponíveis.

openspec schema validate

Verifica a estrutura e os modelos de um esquema.

openspec schema validate spec-driven   # um esquema, de qualquer origem
openspec schema validate               # todos os esquemas locais ao projeto

Ele verifica se schema.yaml existe e é interpretável, se a estrutura corresponde ao formato de esquema, se o arquivo de modelo de cada artefato existe dentro do diretório templates/ do esquema e se o grafo de dependências não tem ciclos ou referências desconhecidas, inclusive em apply.requires. Um valor de apply.tracks que não seja exatamente igual ao valor generates de algum artefato imprime uma linha warning: mas não falha na validação, pois o OpenSpec não consegue determinar a qual progresso de artefato aquele arquivo pertence.

Opções

Flag	Efeito
--json	Imprime um relatório estruturado em vez de texto.
--verbose	Imprime cada etapa da validação.

Saída

✓ Schema 'spec-driven' is valid

Sem um nome, cada esquema do projeto recebe uma linha sob um cabeçalho Validation Results:. Um esquema com falha lista seus problemas e a execução sai com código 1:

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

openspec schema fork

Copia um esquema existente para o projeto para que você possa personalizá-lo.

openspec schema fork spec-driven my-flow

Argumentos

Argumento	O que é
source	O esquema a ser copiado, de qualquer local de origem.
name	Nome para a cópia. Kebab-case (my-workflow). Padrão: <source>-custom.

Opções

Flag	Efeito
--force	Sobrescreve um esquema de destino existente.
--json	Imprime o resultado como JSON.

Saída

✔ 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

O fork é criado em openspec/schemas/, e o campo name: em seu schema.yaml é reescrito para o novo nome:

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

Um destino existente é um erro, a menos que você passe --force. Um fork que mantém o nome da origem oculta o original.

openspec schema init

Cria um novo esquema local ao projeto com modelos iniciais.

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

Sem --description e sem --artifacts em um terminal interativo, init solicita uma descrição, uma lista de verificação de artefatos e se o esquema deve se tornar o padrão do projeto. Fora de um terminal, ele usa os padrões abaixo.

Argumentos

Argumento	O que é
name	Nome para o novo esquema. Kebab-case (my-workflow).

Opções

Flag	Efeito
--description <text>	Descrição do esquema. Padrão: Custom workflow schema for <name>.
--artifacts <list>	IDs de artefatos separados por vírgula de proposal, specs, design, tasks. Padrão: todos os quatro.
--default	Escreve schema: <name> no openspec/config.yaml ou openspec/config.yml existente. Cria openspec/config.yaml se nenhum existir. Novas alterações usam este esquema.
--no-default	Pula a pergunta sobre o padrão.
--force	Sobrescreve um esquema existente com o mesmo nome.
--json	Imprime o resultado como JSON.

A criação do esquema e a atualização da configuração --default são uma única operação. Se o OpenSpec não puder validar ou gravar a configuração, ele deixa tanto a configuração quanto qualquer esquema existente inalterados.

Saída

✔ Created schema 'my-schema'

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

Artifacts: proposal, tasks

A estrutura no disco:

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

O schema.yaml conecta os artefatos selecionados com suas dependências. Quando tasks está incluído, ele também recebe uma fase apply que rastreia tasks.md. Use o esquema com openspec new --schema my-schema.

openspec store

Cria e gerencia stores: repositórios OpenSpec independentes registrados na sua máquina.

openspec store setup team-context --path ~/openspec/team-context   # cria e registra
openspec store register ~/stores/design-system                     # registra um checkout existente
openspec store list                                                # vê o que está registrado

Os registros ficam em um registro por máquina: ~/.local/share/openspec/stores/registry.yaml, ou $XDG_DATA_HOME/openspec/stores/registry.yaml quando XDG_DATA_HOME está definido. Cada subcomando aceita --json para imprimir um relatório estruturado em vez de texto. Executar openspec store com um subcomando ausente ou desconhecido sai com código 1 e lista os subcomandos.

Subcomando	O que faz
setup [id]	Cria uma pasta de store e a registra.
register [path]	Registra uma pasta de store existente.
unregister <id>	Esquece o registro. A pasta permanece no disco.
remove <id>	Esquece o registro e exclui a pasta.
list (alias ls)	Lista stores registradas.
doctor [id]	Verifica registro, metadados e estado do Git para stores registradas.

openspec store setup

Cria uma pasta de store e a registra.

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

Em um terminal interativo, setup solicita um nome e local ausentes e confirma antes de criar qualquer coisa. Fora de um, um nome ou --path ausente sai com código 1 e a flag a ser passada. Executar setup novamente para uma store já registrada informa Registry: already registered.

Setup sai com código 1 com store_setup_inside_git_repo quando --path está dentro de outro repositório Git, pois inicializar a store ali aninharia um repositório dentro de outro. --no-init-git não cria repositório, então pula essa verificação. Use-o para manter uma store em ~/openspec/<id> quando seu diretório inicial for ele próprio um repositório Git, como um repositório de dotfiles.

Argumentos

Argumento	O que é
id	O nome da store. Ele se torna o id que você passa para --store.

Opções

Flag	Efeito
--path <path>	Pasta onde a store deve ficar (~ é expandido).
--init-git	Inicializa um repositório Git com um commit inicial. Padrão.
--no-init-git	Pula toda ação do Git: sem init, sem commit inicial.
--remote <url>	Fonte de clonagem canônica registrada em store.yaml.

Saída

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 informa o que foi criado e onde foi registrado:

{
  "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 uma pasta de store existente, por exemplo, a store de um colega que você clonou.

openspec store register ~/stores/design-system

A pasta deve conter uma raiz openspec/ saudável. Com .openspec-store/store.yaml presente, register reutiliza o id registrado. Sem ele, register pergunta antes de criar esses metadados. Fora de um terminal interativo, passe --yes em vez disso. Uma máquina pode registrar um checkout por id de store. Um segundo caminho sob o mesmo id, ou o mesmo caminho sob um segundo id, sai com código 1.

Argumentos

Argumento	O que é
path	A pasta da store a ser registrada (~ é expandido). Obrigatório.

Opções

Flag	Efeito
--id <id>	Id da store. Padrão: metadados ou nome da pasta.
--yes	Confirma a criação de metadados de identidade da store para uma raiz OpenSpec saudável.

Saída

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

--json imprime a mesma forma de documento que store setup --json.

openspec store unregister

Esquece o registro. A pasta permanece no disco.

openspec store unregister design-system

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

openspec store remove

Esquece o registro e exclui a pasta.

openspec store remove design-system --yes

Interativamente, remove pergunta antes de excluir. Com --json ou fora de um terminal interativo, a exclusão exige --yes:

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

Remove sai com código 1 e não exclui nada quando a pasta não tem metadados de store correspondentes, ou quando contém outra store registrada (por exemplo, uma store fornecida como submódulo Git). Nesse caso, o erro é store_remove_contains_registered_store: execute openspec store unregister <nested-id> primeiro, ou openspec store unregister <id> para esquecer a store sem excluir arquivos.

Opções

Flag	Efeito
--yes	Confirma a exclusão da pasta local da store.

Saída

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

openspec store list

Lista stores registradas. ls é um alias.

openspec store list

OpenSpec stores (2)

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

Com nada registrado, list imprime No stores registered. e os comandos setup e register a executar em seguida.

openspec store doctor

Verifica registro, metadados e estado do Git para stores registradas.

openspec store doctor                # toda store registrada
openspec store doctor team-context  # uma store

Saída

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

Códigos de saída

• 0: o relatório foi impresso, mesmo quando uma store relata problemas.
• 1: o relatório não pôde ser executado (por exemplo, um id de store desconhecido).

openspec doctor

Relata a integridade dos relacionamentos da raiz do OpenSpec resolvida.

openspec doctor                       # raiz openspec/ mais próxima acima do seu cwd
openspec doctor --store team-context  # um store registrado como a raiz

O Doctor é somente leitura: ele nunca faz clone, sincronização ou reparo. Ele informa se a raiz está íntegra e se cada referência declarada em openspec/config.yaml é resolvida nesta máquina. Sem uma raiz acima do seu cwd e sem --store, ele encerra com código 1 e informa os nomes dos seus stores registrados.

Opções

Flag	Efeito
--store <id>	Usa um store registrado como a raiz do OpenSpec em vez do projeto atual.
--json	Imprime o relatório de integridade como JSON.

Saída

Doctor

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

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

Com --store, a raiz é o store e o relatório adiciona uma linha de 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)

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

Códigos de saída

• 0: o relatório foi impresso, inclusive quando lista problemas.
• 1: nenhuma raiz foi resolvida (nenhum openspec/ acima do seu cwd e nenhum --store), ou um id de --store desconhecido.

openspec context

Imprime o contexto de trabalho para a raiz do OpenSpec resolvida: a raiz mais cada store referenciado declarado em openspec/config.yaml, cada um com um comando de busca.

openspec context                       # raiz openspec/ mais próxima acima do seu cwd
openspec context --store team-context  # um store registrado como a raiz
openspec context --json                # briefing do agente

Referências que não são resolvidas nesta máquina aparecem em uma seção Not available on this machine, cada uma com uma correção.

Opções

Flag	Efeito
--store <id>	Usa um store registrado como a raiz do OpenSpec em vez do projeto atual.
--json	Imprime o briefing do agente como JSON.
--code-workspace <path>	Também grava um arquivo de workspace do VS Code para o conjunto.
--force	Sobrescreve um arquivo --code-workspace existente.

Saída

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

Com --store, o store é o conjunto inteiro:

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

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

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

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

Gravando um arquivo de workspace

--code-workspace grava um arquivo de workspace do VS Code no caminho informado: uma pasta para a raiz, uma pasta ref:<id> por store referenciado disponível. Referências indisponíveis são ignoradas e nomeadas na linha de resumo, Wrote /Users/you/projects/my-app/openspec.code-workspace (2 folders). O resumo é impresso em stderr, portanto a saída padrão de --json permanece um único documento JSON. Um arquivo existente faz o comando encerrar com código 1, a menos que você passe --force.

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

Códigos de saída

• 0: o relatório foi impresso.
• 1: nenhuma raiz foi resolvida (nenhum openspec/ acima do seu cwd e nenhum --store), ou a gravação de --code-workspace foi recusada.

openspec workset

Compõe, mantém e abre visões de trabalho pessoais. Um workset é uma lista salva e nomeada de pastas nas quais você trabalha em conjunto.

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

Subcomando	O que faz
create [name]	Compõe e salva uma visão de trabalho nomeada das pastas que você escolher.
list, ls	Mostra os worksets salvos com seus membros.
open <name>	Abre um workset salvo na sua ferramenta (janela de editor ou sessão de agente).
remove <name>	Exclui um workset salvo (as pastas membro nunca são alteradas).

Um workset é puramente local:

• Seu estado vive em uma única pasta: ~/.local/share/openspec/worksets/ ($XDG_DATA_HOME/openspec/worksets/ quando definida; %LOCALAPPDATA%\openspec\worksets\ no Windows).
• Nada é gravado nas pastas membro, e nada é submetido a commit ou compartilhado.
• Excluir essa única pasta remove todos os rastros.

openspec workset create

Salva uma visão de trabalho nomeada de pastas.

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

Em um terminal interativo, o create solicita o que as flags não forneceram: o nome, as pastas uma por vez, uma ferramenta e, por fim, uma oferta para abrir o workset agora. Fora de um terminal interativo, nome ou membro ausente é um erro. Um nome já salvo é sempre um erro. Remova-o primeiro.

Argumentos

Argumento	O que é
name	O nome do workset. Kebab-case: letras minúsculas, números, hífens simples. Obrigatório fora de um terminal interativo.

Opções

Flag	Efeito
--member <member>	Pasta membro como <path> ou <name>=<path>, repetível. A primeira é a primária. O caminho deve ser uma pasta existente, e o rótulo assume, por padrão, o próprio nome da pasta.
--tool <id>	Ferramenta preferencial para abrir este workset. Ids integrados: code (VS Code), cursor (Cursor). claude e codex estão temporariamente desativados.
--json	Imprime o workset salvo como JSON.

Saída

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

openspec workset list

Mostra os worksets salvos com seus membros, ordenados por nome.

openspec workset list   # alias: ls

Opções

Flag	Efeito
--json	Imprime os worksets como JSON.

Saída

Um bloco por workset: o nome, sua ferramenta quando tiver uma e, depois, uma linha name path por membro. Sem nada salvo, o list imprime 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

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

Abre um workset salvo na sua ferramenta. Ferramentas de editor (code, cursor) recebem um arquivo .code-workspace gerado. Uma janela é aberta e o comando retorna. Ferramentas de agente CLI (claude, codex) assumiriam este terminal com todos os membros anexados. Elas estão temporariamente desativadas enquanto esse fluxo é reformulado, então, por enquanto, os worksets abrem em uma IDE.

openspec workset open checkout                # ferramenta salva, ou um prompt
openspec workset open checkout --tool cursor  # esta ferramenta apenas nesta vez

Argumentos

Argumento	O que é
name	O workset a ser aberto.

Opções

Flag	Efeito
--tool <id>	Abre com esta ferramenta apenas nesta vez.

Sem --tool e sem ferramenta salva, o open solicita que você escolha uma ferramenta instalada. Fora de um terminal interativo, ele termina com código 1.

• Uma pasta membro que não existe mais é ignorada com um aviso. Quando a primária está ausente, o próximo membro remanescente torna-se a primária para esta abertura. Quando nenhuma pasta membro existe, a abertura falha.
• --json é rejeitado: o open entrega o terminal à ferramenta e não tem modo JSON.
• Quando o lançamento falha, o erro termina com a rota manual: o caminho do arquivo de workspace e a lista de membros.

Códigos de saída

• Espelha a ferramenta: o comando termina com o próprio código de saída da ferramenta, e um sinal torna-se 128+n (130 após Ctrl-C).
• 1: workset desconhecido, nenhuma pasta membro disponível ou nenhuma ferramenta utilizável.

openspec workset remove

Exclui um workset salvo e seu arquivo .code-workspace gerado. As pastas membro nunca são alteradas.

openspec workset remove checkout --yes

Em um terminal interativo, o remove mostra o workset e pede que você confirme. Com --json, ou fora de um terminal, ele exige --yes e termina com código 1 sem ele.

Opções

Flag	Efeito
--yes	Confirma a remoção de forma não interativa.
--json	Imprime a remoção como JSON.

Saída

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

openspec version

Relata a versão do OpenSpec em execução e como esta cópia foi instalada.

openspec version                 # versão local e detalhes da instalação
openspec version --json          # relatório local estruturado
openspec version --check         # também verifica o registro em busca de atualização
openspec version --check --json  # relatório local e de atualização estruturado

Sem --check, este comando é local e não contata nenhum registro. Funciona fora de um projeto OpenSpec. A flag existente openspec --version continua sendo a forma mais curta e imprime apenas o número puro da versão.

Opções

Flag	Efeito
--json	Imprime um documento JSON versionado em vez de texto.
--check	Verifica no registro configurado se há um lançamento mais recente.

Saída

Para uma instalação global via npm:

OpenSpec 1.13.2 (npm, global)

O escopo de instalação é global, project, temporary para um runner efêmero como o npx, source para um checkout do código-fonte, ou standalone para a instalação standalone. O OpenSpec omite detalhes que não consegue identificar em vez de adivinhar.

--json mantém os detalhes desconhecidos como valores null explícitos:

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

Com --check, uma atualização disponível adiciona a versão mais recente e um comando quando o OpenSpec consegue identificar um comando seguro para essa instalação:

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

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

Valores de status de atualização:

Status	Significado
available	O registro retornou uma versão segura mais nova que a versão em execução.
current	A verificação foi concluída e não encontrou nenhuma versão mais nova.
disabled	Uma configuração existente de privacidade ou de verificação de atualizações bloqueou o acesso ao registro. latest é null.
offline	O registro estava indisponível ou retornou uma resposta inutilizável. latest é null.

Para a instalação standalone, o comando de atualização é openspec install.

DO_NOT_TRACK, opt-outs de telemetria, OPENSPEC_NO_UPDATE_CHECK, detecção de CI e sobrescritas de registro não HTTPS rejeitadas desativam a verificação. Verificações desativadas e offline ainda terminam com código 0 porque a disponibilidade de atualização é apenas informativa. Este comando nunca faz upgrade do OpenSpec; canSelfUpgrade apenas informa se o caminho existente openspec update poderia fazer o upgrade desta cópia com segurança.

Códigos de saída

• 0: o relatório local foi impresso, incluindo verificações de atualização desativadas ou offline.
• 1: a sintaxe do comando era inválida, como a opção não suportada --upgrade.

openspec install

Instala o openspec autônomo. Execute-o a partir de uma instalação via npm ou Homebrew para alternar, ou a partir da instalação autônoma para atualizá-lo no local.

openspec install          # versão mais recente
openspec install 1.15.0   # uma versão específica

Ele executa o script de instalação, que escolhe a versão mais recente que tenha todos os arquivos anexados, seleciona o arquivo para a sua máquina e o confere em relação ao SHA256SUMS dessa versão:

• De um gerenciador de pacotes: instala em ~/.local/bin (Windows: %LOCALAPPDATA%\Programs\openspec) e imprime o comando que remove a cópia antiga, como npm uninstall -g @fission-ai/openspec. Ele nunca remove essa cópia por conta própria.
• Da instalação autônoma: substitui o arquivo em execução no próprio local, mantendo seu nome.

Depois, ele informa qual cópia do openspec passa a ser executada agora, já que uma cópia instalada pelo gerenciador de pacotes que esteja antes no seu PATH continua sendo executada até você removê-la.

Argumentos

Argumento	O que é
version	Versão de lançamento a instalar, como 1.15.0. Opcional; o padrão é a mais recente.

OPENSPEC_INSTALL_DIR e OPENSPEC_INSTALL_NAME escolhem outra pasta ou outro nome de arquivo.

Códigos de saída

• 0: instalado.
• 1: a versão não é uma versão de lançamento, ou o download ou a instalação falhou. Sua cópia atual é deixada como estava.

openspec feedback

Envia feedback sobre o OpenSpec.

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

A CLI registra sua mensagem como uma issue do GitHub no repositório Fission-AI/OpenSpec por meio da sua CLI gh. O título se torna Feedback: <message>. O corpo usa os títulos do formulário de bug: sua mensagem em What happened, o texto de --body em Details e uma seção Minimal steps to reproduce solicitando que você adicione as etapas, já que a CLI não consegue preenchê-las. Um rodapé adiciona a versão da CLI, a plataforma e o carimbo de data/hora. A issue recebe o rótulo feedback. Se o repositório não definir esse rótulo, a CLI tenta novamente sem ele e informa isso.

Argumentos

Argumento	O que é
message	Resumo de uma linha. Torna-se o título da issue. Obrigatório.

Opções

Opção	Efeito
--body <text>	Descrição mais longa adicionada ao corpo da issue.

Saída

Em caso de sucesso:

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

Sem o gh instalado, ou com o gh não autenticado, nada é enviado. A CLI imprime seu feedback formatado entre os marcadores --- FORMATTED FEEDBACK --- e, em seguida, um link que abre o formulário de relatório de bug com o título, o que aconteceu (sua mensagem e o texto de --body), a versão da CLI e o ambiente (plataforma e versão do Node) preenchidos. Você completa o restante do formulário no navegador. O caminho sem autenticação adiciona To auto-submit in the future: gh auth login.

Códigos de saída

• 0: issue criada, ou o fallback de envio manual foi executado (sem gh ou gh não autenticado).
• 1: nenhuma mensagem fornecida.
• Código próprio do gh: o gh falhou após a autenticação (rede, limite de requisições, issues desabilitadas). A CLI reimprime seu feedback e a URL de envio manual primeiro.

openspec completion

Instala ou gera completions de shell.

openspec completion install        # detecta seu shell, instala e configura
openspec completion generate zsh   # imprime o script no stdout

Shells compatíveis: zsh, bash, fish, powershell. Todo subcomando aceita um argumento opcional de shell. Se você omiti-lo, a CLI detecta seu shell a partir do ambiente.

Subcomando	O que faz
generate [shell]	Imprime o script de completion no stdout.
install [shell]	Grava o script e configura o arquivo de inicialização do seu shell.
uninstall [shell]	Remove o script e o bloco de configuração.

Quando instalado com Nix, as completions já estão no lugar: o pacote flake inclui os scripts para Bash, Fish e Zsh nos locais padrão, então install não é necessário (Instalação).

openspec completion generate

Imprime o script e não grava nada.

#compdef openspec

# Script de completion Zsh para a CLI do OpenSpec
# Gerado automaticamente - não edite manualmente

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

openspec completion install

Grava o script e edita a configuração do seu shell. As edições de configuração ficam entre os marcadores # OPENSPEC:START e # OPENSPEC:END. Um script existente é copiado como backup primeiro (cópia .backup-<timestamp>).

Shell	Local do script	Configuração editada
zsh	~/.zsh/completions/_openspec	$ZDOTDIR/.zshrc quando ZDOTDIR é um caminho absoluto; caso contrário, ~/.zshrc
bash	~/.local/share/bash-completion/completions/openspec	~/.bashrc
fish	~/.config/fish/completions/openspec.fish	Nenhuma: o fish o carrega automaticamente.
powershell	OpenSpecCompletion.ps1 ao lado do seu perfil	$PROFILE

Com o Oh My Zsh instalado, o script fica em $ZSH_CUSTOM/completions/_openspec (padrão: ~/.oh-my-zsh/custom/completions/_openspec).

Um ZDOTDIR relativo ou prefixado com ~ é ignorado, e ~/.zshrc é editado. Executar install novamente quando o script já está atualizado ainda adiciona o bloco ao .zshrc lido pelo zsh.

Opções

Opção	Efeito
--verbose	Também imprime o caminho instalado, qualquer caminho de backup e qual arquivo de configuração foi editado.

Saída

✓ Completion script installed and .zshrc configured successfully

Restart your shell or run: exec zsh

openspec completion uninstall

Remove o script e o bloco de configuração marcado. Ele pergunta antes de modificar sua configuração (padrão: Não).

Para zsh, ele limpa o .zshrc que o install edita e também ~/.zshrc quando uma instalação mais antiga deixou um bloco ali sob ZDOTDIR. Se um bloco não puder ser removido, o uninstall informa o arquivo e encerra com código 1.

Opções

Opção	Efeito
-y, --yes	Ignora os prompts de confirmação.

Saída

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

Códigos de saída

• 0: script gerado, instalado ou removido. Uma desinstalação cancelada também encerra com 0.
• 1: shell não suportado ou não detectado, ou uma etapa de instalação ou desinstalação falhou.

openspec change

Forma nominal obsoleta de show, list e validate. Toda execução emite um aviso, aponta para os comandos iniciados por verbo e, em seguida, executa mesmo assim:

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

Obsoleto	Use em vez disso
openspec change show <name>	openspec show <name>
openspec change list	openspec list
openspec change validate <name>	openspec validate <name> (todas as mudanças: openspec validate --changes)

As seções iniciadas por verbo documentam as flags.

openspec spec

Forma nominal obsoleta de show, list e validate. Toda execução emite um aviso, aponta para os comandos iniciados por verbo e, em seguida, executa mesmo assim:

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

Obsoleto	Use em vez disso
openspec spec show <id>	openspec show <id>
openspec spec list	openspec list --specs
openspec spec validate <id>	openspec validate <id> (todas as specs: openspec validate --specs)

As seções iniciadas por verbo documentam as flags.