Referência da CLI

A CLI do OpenSpec (openspec) oferece comandos de terminal para configurar projetos, validar conteúdo, consultar status e gerenciar recursos. Esses comandos complementam os comandos de barra para IA (como /opsx:propose) descritos em Comandos.

Resumo

Categoria	Comandos	Finalidade
Configuração	init, update	Inicializar e atualizar o OpenSpec no projeto
Stores (repositórios OpenSpec independentes)	store setup, store register, store unregister, store remove, store list, store doctor	Gerenciar stores — repositórios OpenSpec independentes que você registrou
Integridade	doctor	Informar a integridade das relações da raiz resolvida
Contexto de trabalho	context	Reunir o conjunto de trabalho (raiz + stores referenciadas)
Worksets pessoais	workset create, workset list, workset open, workset remove	Manter e abrir visões de trabalho locais e pessoais na sua ferramenta
Navegação	list, view, show	Explorar mudanças e especificações
Validação	validate	Verificar se há problemas nas mudanças e especificações
Ciclo de vida	archive	Finalizar mudanças concluídas
Fluxo de trabalho	new change, status, instructions, templates, schemas	Oferecer suporte a fluxos orientados por artefatos
Schemas	schema init, schema fork, schema validate, schema which	Criar e gerenciar fluxos de trabalho personalizados
Configuração	config	Consultar e modificar configurações
Utilitários	feedback, completion	Enviar comentários e integrar ao shell

---

Comandos para pessoas e agents

A maioria dos comandos da CLI foi projetada para uso por pessoas no terminal. Alguns também aceitam uso por agents/scripts, por meio de saída JSON.

Comandos somente para pessoas

Estes comandos são interativos e foram projetados para uso no terminal:

Comando	Finalidade
openspec init	Inicializar o projeto (prompts interativos)
openspec view	Abrir dashboard interativo
openspec workset open <name>	Abrir um workset salvo (janela do editor ou sessão de agent no terminal)
openspec config edit	Abrir a configuração no editor
openspec feedback	Enviar comentários pelo GitHub
openspec completion install	Instalar conclusões de comando no shell

Comandos compatíveis com agents

Estes comandos aceitam a saída --json para uso programático por AI agents e scripts:

Comando	Uso por pessoas	Uso por agents
openspec list	Navegar por mudanças/especificações	--json para dados estruturados
openspec show <item>	Ler conteúdo	--json para análise
openspec validate	Verificar problemas	--all --json para validação em lote
openspec status	Consultar o progresso dos artefatos	--json para um status estruturado
openspec instructions	Obter as próximas etapas	--json para instruções do agent
openspec templates	Localizar caminhos dos templates	--json para resolver caminhos
openspec schemas	Listar schemas disponíveis	--json para descobrir schemas; --store <id> para selecionar uma raiz registrada
openspec store setup <id>	Criar e registrar uma store local	--json com entradas explícitas para uma saída estruturada
openspec store register <path>	Registrar uma store existente	--json para uma saída estruturada do registro
openspec store unregister <id>	Esquecer um registro local de store	--json para uma saída estruturada da limpeza
openspec store remove <id>	Excluir a pasta de uma store local registrada	--yes --json para excluir sem interação
openspec store list	Navegar pelas stores registradas	--json para registros estruturados
openspec store doctor	Verificar a configuração da store local	--json para diagnósticos estruturados
openspec new change <id>	Criar a estrutura de uma mudança local ao repositório	--json e --store <id> para usar uma store registrada como raiz do OpenSpec
openspec workset create [name]	Compor uma visão de trabalho pessoal	--member <path> --json para compor sem interação
openspec workset list	Navegar pelos worksets salvos	--json para visões estruturadas
openspec workset remove <name>	Excluir uma visão salva	--yes --json para remover sem interação

---

Opções globais

Estas opções funcionam com todos os comandos:

Opção	Descrição
--version, -V	Exibir o número da versão
--no-color	Desabilitar cores na saída
--help, -h	Exibir a ajuda do comando

---

Comandos de configuração

openspec init

Inicialize o OpenSpec no projeto. Cria a estrutura de pastas e configura as integrações com ferramentas de IA.

Por padrão, usa os valores globais: profile core, distribuição both e fluxos de trabalho propose, explore, apply, update, sync, archive.

openspec init [path] [options]

Use --language <language> para adicionar uma instrução de idioma ao openspec/config.yaml de um projeto novo. Em um projeto existente, edite o campo context da configuração para que o OpenSpec nunca substitua as orientações específicas do projeto.

Argumentos:

Argumento	Obrigatório	Descrição
path	Não	Diretório de destino (padrão: diretório atual)

Opções:

Opção	Descrição
--tools <list>	Configurar ferramentas de IA sem interação. Use all, none ou uma lista separada por vírgulas
--language <language>	Usar este idioma nos artefatos ao criar uma nova configuração
--force	Limpar arquivos legados automaticamente, sem perguntar
--profile <profile>	Substituir o profile global nesta execução de init (core ou custom)
--no-animation	Exibir uma tela de boas-vindas estática em vez da animada
--copilot-cloud	Configurar, sem perguntar, os arquivos do coding agent na nuvem do GitHub Copilot
--no-copilot-cloud	Ignorar, sem perguntar, os arquivos do coding agent na nuvem do GitHub Copilot

--profile custom usa os fluxos de trabalho selecionados atualmente na configuração global (openspec config profile).

A animação de boas-vindas também é ignorada quando a variável de ambiente OPENSPEC_NO_ANIMATION está definida (com qualquer valor, inclusive vazio), quando NO_COLOR tem um valor não vazio ou quando a preferência de movimento reduzido do sistema operacional está habilitada (Reduce Motion no macOS ou animações desabilitadas no GNOME).

IDs de ferramentas aceitos (--tools) — windsurf também é aceito como alias de devin: amazon-q, antigravity, auggie, bob, claude, cline, command-code, codeartsagent, codex, devin, forgecode, codebuddy, continue, costrict, crush, cursor, factory, gemini, github-copilot, hermes, iflow, junie, kilocode, kimi, kiro, lingma, minimax-code, vibe, oh-my-pi, opencode, pi, codeassistant, qoder, qwen, rovodev, roocode, trae, zed, zcode, agents

Esta lista corresponde a AI_TOOLS em src/core/config.ts. Consulte Ferramentas compatíveis para ver os caminhos de skills e comandos de cada ferramenta.

Exemplos:

# Interactive initialization
openspec init

# Initialize in a specific directory
openspec init ./my-project

# Non-interactive: configure for Claude and Cursor
openspec init --tools claude,cursor

# Non-interactive: configure global MiniMax Code skills
openspec init --tools minimax-code

# Configure for all supported tools
openspec init --tools all

# Override profile for this run
openspec init --profile core

# Skip prompts and auto-cleanup legacy files
openspec init --force

O que cria:

openspec/
├── specs/              # Your specifications (source of truth)
├── changes/            # Proposed changes
└── config.yaml         # Project configuration

.claude/skills/         # Claude Code skills (if claude selected)
.cursor/skills/         # Cursor skills (if cursor selected)
.cursor/commands/       # Cursor OPSX commands (if delivery includes commands)
.agents/skills/         # Shared skills for AGENTS.md-compatible tools (if agents selected)
... (other tool configs)

---

openspec update

Atualize os arquivos de instruções do OpenSpec depois de atualizar a CLI. O comando gera novamente os arquivos de configuração das ferramentas de IA com base no profile global, nos fluxos de trabalho selecionados e no modo de distribuição atuais.

openspec update [path] [options]

Argumentos:

Argumento	Obrigatório	Descrição
path	Não	Diretório de destino (padrão: diretório atual)

Opções:

Opção	Descrição
--force	Forçar a atualização mesmo quando os arquivos estiverem atualizados
--dry-run	Informar o que a atualização alteraria, sem gravar nada
--json	Com --dry-run, exibir as alterações planejadas em JSON

Exemplo:

# Update instruction files after npm upgrade
npm install -g @fission-ai/openspec@latest
openspec update

Pré-visualizando uma atualização:

--dry-run informa os arquivos que uma atualização adicionaria, alteraria ou excluiria, sem gravar nada. Os caminhos são relativos ao projeto; arquivos fora dele (skills no seu diretório pessoal) aparecem com o prefixo ~/.

openspec update --dry-run --json

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

O plano é o que uma execução não interativa faz e lista todos os arquivos que ela tocaria: movimentações para fora do diretório anterior de uma ferramenta, o salvamento da configuração global em uma instalação anterior aos profiles, os arquivos do cloud agent do Copilot e, com --force, a limpeza de artefatos legados. Arquivos que pertencem ao próprio OpenSpec, e não a uma ferramenta, têm tool: "openspec". notes sinaliza etapas sobre as quais um usuário de terminal seria consultado, cada uma com um code estável: legacy-tool-directories (uma movimentação listada como feita) e legacy-artifacts (arquivos do layout antigo que a atualização mantém sem --force). failures lista as ferramentas nas quais a atualização real falharia, incluindo gravações que ela não consegue fazer (um diretório no lugar de um arquivo, sem permissão de gravação); para essa ferramenta, o plano para no ponto em que a atualização pararia, e uma ferramenta com problema não compromete o restante do plano. Ambos ficam vazios em uma atualização comum. O guia completo está em openspec.dev/docs/cli.

Um fracasso de --dry-run --json ainda imprime exatamente um documento JSON, o plano vazio mais um array status, e termina com código diferente de zero.

Atualize primeiro o pacote. Os arquivos de instruções são gerados pela CLI instalada; portanto, executar openspec update com uma instalação desatualizada informa que tudo está atualizado, sem adicionar os fluxos de trabalho incluídos em versões mais recentes.

Para deixar isso claro, openspec update consulta o registro do npm para saber se foi publicada uma CLI mais recente. Se a sua estiver desatualizada, o comando oferecerá uma atualização:

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

Se você responder sim, o comando executará npm install -g @fission-ai/openspec@latest e, em seguida, repetirá a atualização com a nova CLI para incluir os novos fluxos no mesmo comando. A confirmação da atualização consulta a versão do executável instalado, em vez de confiar no código de saída do npm. Assim, se outra instalação anterior no PATH ainda estiver sendo usada, o comando avisará você em vez de declarar sucesso. Se responder não, ele exibirá o comando e atualizará usando a CLI atual. Ctrl-C interrompe o comando.

A oferta aparece somente em um terminal interativo e quando a instalação é gerenciada pelo npm — o único caso em que npm install -g realmente resolve o problema. Para os demais casos, é exibido o comando correspondente ao método de instalação:

Como o OpenSpec foi instalado	O que será exibido
Instalação global com npm	O prompt, com atualização automática no terminal interativo; em saídas redirecionadas, é exibido o comando
Instalação global com pnpm, bun, yarn ou volta	O comando do respectivo gerenciador: pnpm add -g …@latest, bun add -g …@latest, yarn global add …@latest ou volta install …@latest
Dependência do projeto	Um aviso para atualizar a dependência, pois o gerenciador do projeto controla o arquivo de lock
Cache de npx/dlx	npx @fission-ai/openspec@latest update — esse comando já faz a atualização, sem uma segunda etapa
Clone do Git	Nenhum — a versão é determinada pela branch

Sempre que algo for exibido, será indicado o diretório de onde a CLI em execução foi carregada — confira-o caso você tenha atualizado, mas um shim antigo ainda esteja sendo usado pelo PATH.

O registro consultado é o indicado por npm_config_registry, quando exportado pelo npm; caso contrário, usa-se https://registry.npmjs.org. Nenhum arquivo .npmrc é lido: não é recomendável deixar o conteúdo de um arquivo determinar o destino de uma solicitação externa, e o .npmrc do projeto acompanha o repositório. Para usar um espelho privado, exporte npm_config_registry ou defina OPENSPEC_NO_UPDATE_CHECK para ignorar completamente a verificação. Ela também é ignorada quando CI está definido com qualquer valor que não seja explicitamente desativado (false, 0, no, off ou vazio), quando NODE_ENV=test e quando OPENSPEC_NO_UPDATE_CHECK (qualquer valor), DO_NOT_TRACK=1 ou OPENSPEC_TELEMETRY=0 estiver definido. A verificação ocorre antes da atualização e pode atrasá-la em no máximo 1,5 segundo; depois desse limite, desiste mesmo que a rede esteja descartando pacotes sem aviso e permanece silenciosa se o registro estiver indisponível.

Como é determinada a atualização: os arquivos de skills registram a versão que os gerou, e o OpenSpec a compara com a CLI instalada. Arquivos de comando não têm marca de versão; portanto, para uma ferramenta que usa comandos, mas não skills (distribuição commands), o OpenSpec compara o conteúdo dos arquivos com o que geraria agora. Alterações nesses arquivos são consideradas divergências e sobrescritas. Com a distribuição skills ou both, somente a versão registrada é verificada; um arquivo editado manualmente cuja versão ainda corresponda é mantido. Use --force para regravá-lo. Em ambos os casos, os arquivos gerados pertencem ao OpenSpec; mantenha suas próprias instruções em outro lugar.

---

Stores (repositórios OpenSpec independentes)

Beta. Stores e os recursos que dependem delas (referências, contexto de trabalho e worksets) são novos; nomes de comandos, opções, formatos de arquivo e saídas JSON podem mudar entre versões. Para ver um guia organizado em torno dos problemas que eles resolvem, consulte o guia de stores.

Uma store é um repositório OpenSpec independente registrado nesta máquina — por exemplo, um repositório de planejamento ou contratos. Ao registrar uma store, os comandos normais (list, show, status, validate, new change, archive…) podem atuar nela de qualquer lugar usando --store <id>.

openspec store setup

Crie e registre uma store local. Se não forem fornecidos argumentos no terminal, o OpenSpec orientará a pessoa usuária durante a configuração. Agents e scripts devem fornecer entradas explícitas e usar --json.

openspec store setup [id] [options]

Opções:

Opção	Descrição
--path <path>	Pasta da store (por exemplo, ~/openspec/<id>)
--remote <url>	Registrar o remoto canônico no store.yaml da nova store
--init-git	Inicializar um repositório Git com um commit inicial (padrão)
--no-init-git	Ignorar todas as ações do Git: sem init e sem commit inicial
--json	Gerar saída JSON

Execuções não interativas (--json, scripts, agents) precisam receber o ID da store e --path. Em um terminal interativo, setup pergunta o local e sugere um caminho editável em um diretório visível e pertencente à pessoa usuária (por exemplo, ~/openspec/<id>); nunca usa como padrão o diretório de dados gerenciado pelo OpenSpec.

Exemplos:

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

openspec store register

Registre uma pasta de store local existente. Durante a versão beta, uma raiz pode ser registrada antes que existam mudanças, especificações aplicadas ou mudanças arquivadas; nesse caso, openspec/changes/, openspec/specs/ e openspec/changes/archive/ podem não existir até que comandos normais as criem. Um repositório somente de configuração que declare store: <id> continua sendo um ponteiro para outra store e não é registrado como raiz de store, a menos que esse ponteiro seja removido.

openspec store register [path] [options]

Opções:

Opção	Descrição
--id <id>	ID da store; o padrão é o indicado nos metadados da store ou o nome da pasta
--yes	Confirmar a criação de metadados de identidade para uma raiz íntegra do OpenSpec
--json	Gerar saída JSON

openspec store unregister

Esqueça o registro de uma store local sem excluir arquivos.

openspec store unregister <id> [--json]

Use-o quando uma store tiver sido movida ou clonada para outro local, ou quando não quiser mais que o OpenSpec a exiba nesta máquina.

openspec store remove

Esqueça o registro de uma store local e exclua sua pasta.

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

Em um terminal interativo, remove exibe o caminho exato antes de excluir a pasta. Agents, scripts e chamadas JSON precisam passar --yes para confirmar a exclusão. O OpenSpec não exclui uma pasta sem os metadados correspondentes da store.

openspec store list

Liste as stores registradas localmente.

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

openspec store doctor

Verifique o registro local da store, seus metadados e a presença do Git.

openspec store doctor [id] [--json]

doctor serve apenas para diagnóstico: informa sobre raízes ausentes, divergências nos metadados e estados inválidos do registro local, sem modificar a store.

Referenciar stores em um projeto

Um repositório de projeto pode declarar em openspec/config.yaml quais stores servem de base ao trabalho:

schema: spec-driven
references:
  - team-context

A partir daí, a saída de openspec instructions nesse repositório — tanto para cada artefato quanto para apply, nos modos JSON e legível por pessoas — inclui um índice das especificações de cada store referenciada: IDs de especificação, um resumo de uma linha da seção Purpose e o comando para consultá-la (openspec show <spec-id> --type spec --store <id>). O índice é montado em tempo real a partir do checkout registrado a cada execução; o conteúdo das especificações nunca é copiado para a saída.

As referências são contexto somente para leitura. Elas nunca alteram onde os comandos atuam: o trabalho continua na raiz do próprio repositório, e gravar em uma store referenciada ainda exige a opção explícita --store. Uma referência que não puder ser resolvida (por exemplo, uma store não registrada nesta máquina) é substituída por um aviso no índice com a correção exata, e as instruções continuam sendo geradas. openspec doctor apresenta a integridade das referências em um só lugar.

Registrar a origem do clone de uma store

Uma store pode registrar a origem canônica do clone em seu arquivo de identidade versionado, para que o processo de integração não pare em “registre a store”:

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

O remoto é registrado em .openspec-store/store.yaml no commit inicial, para que todo clone já o conheça. Em uma store existente, edite store.yaml manualmente e faça commit. store doctor exibe o remoto registrado (e a origem Git detectada no checkout); as instruções de compartilhamento de setup/register o indicam; e register registra a origem do checkout no registro local da máquina.

Uma declaração de referência também pode incluir a origem do clone, para que quem ainda não tenha a store receba uma correção completa, pronta para copiar e colar (git clone <remote> <path> && openspec store register <path> --id <id>):

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

Registrar um remoto não é sincronizar: o OpenSpec nunca clona, faz pull ou push por conta própria.

Declarar uma store padrão

Um repositório cujo planejamento foi totalmente externalizado — sem openspec/specs/ nem openspec/changes/ locais — pode declarar sua store uma única vez, em vez de passar --store a cada comando:

# openspec/config.yaml (the only file under openspec/)
store: team-context

Os comandos normais passam a usar automaticamente a store declarada; o banner da raiz e o bloco JSON root informam source: "declared" e o ID da store, enquanto as sugestões impressas continuam incluindo --store <id>. A declaração é um fallback, nunca uma substituição: --store explícito sempre prevalece, e um diretório com pastas reais de planejamento ignora o ponteiro (com um aviso). Para converter um repositório com ponteiro em uma raiz local do OpenSpec, remova a linha store: e execute openspec init — init não cria a estrutura enquanto a declaração existir.

A opção no nível da máquina cobre todos os repositórios de uma só vez: openspec config set defaultStore <id> (consulte Configuração). Ela só é considerada depois que --store, uma raiz local e um ponteiro do projeto não conseguem resolver a raiz; então, o banner e o bloco JSON root informam source: "global_default".

Doctor (integridade das relações)

Uma pergunta somente para leitura, respondida em um só lugar: a raiz do OpenSpec está íntegra e as stores que ela referencia estão disponíveis nesta máquina?

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

O relatório separa a integridade da raiz, dos metadados das stores (inclusive avisos quando o remoto registrado diverge da origem do checkout ou quando o checkout da store está atrasado em relação à sua referência de rastreamento upstream atualizada pela última vez) e das referências (os mesmos diagnósticos exibidos pelas instruções, com correções de clone para referências não resolvidas). Problemas de integridade de qualquer gravidade resultam em código de saída 0 — os agents consultam os arrays status; somente falhas de comando (raiz ausente, store desconhecida) resultam em código 1. doctor nunca clona, sincroniza ou corrige nada. Para obter o conjunto reunido em vez do relatório de integridade, use openspec context.

Contexto de trabalho (o conjunto reunido)

Tudo o que está relacionado ao trabalho segundo as declarações do OpenSpec, reunido em um único conjunto de trabalho: a raiz do OpenSpec e as stores que ela referencia.

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

O resumo JSON pode ser usado por agents (cada store referenciada disponível inclui instruções para consultá-la; membros não resolvidos incluem as mesmas correções exibidas por instructions e doctor). --code-workspace também grava um arquivo de workspace do VS Code com a raiz e as stores referenciadas disponíveis (pastas ref:<id>) — a única gravação feita pelo comando. Se o arquivo já existir, a gravação é recusada sem --force. Membros indisponíveis são informados, nunca presumidos.

“Contexto de trabalho” é o conjunto reunido. O campo context: em openspec/config.yaml contém informações do projeto incluídas nas instruções; são coisas diferentes. openspec doctor informa se o conjunto está íntegro; openspec context informa o que faz parte dele.

Worksets pessoais

Beta. Worksets fazem parte da nova versão beta; comandos, opções e formatos de arquivo podem mudar entre versões. Para ver um guia passo a passo, consulte o guia de stores.

Um workset é uma visão pessoal, identificada por um nome, das pastas que você usa em conjunto — uma raiz de planejamento e quaisquer outras que escolher. Ele fica na sua máquina e pode ser reaberto pelo nome na sua ferramenta. É puramente local: nunca é incluído em commits, compartilhado ou derivado de declarações; sua remoção nunca afeta as pastas dos membros.

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

create executa um fluxo guiado breve (ou recebe opções --member sem interação; o primeiro membro é o principal e as sessões começam nele). open inicia a ferramenta escolhida: editores (VS Code, Cursor) abrem uma janela com todos os membros e retornam; CLI agents (Claude Code, codex) assumem este terminal em uma sessão com todos os membros anexados e sem prompt pré-preenchido, que termina quando você sai. Uma pasta de membro que não existir ao abrir será ignorada, com um aviso; as demais serão abertas. A preferência de ferramenta salva pode ser substituída em cada abertura com --tool.

O suporte a uma ferramenta nova é uma configuração, não uma alteração de código. Cada ferramenta usa um de dois estilos de inicialização — workspace-file (iniciada com o arquivo .code-workspace gerado) ou attach-dirs (uma opção de anexo para cada membro). A chave openers do config.json global (abra-o com openspec config edit) adiciona ferramentas ou ajusta as opções integradas campo a campo:

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

Todo o estado dos worksets fica na pasta worksets/ do diretório global de dados (as visões salvas e os arquivos <name>.code-workspace gerados, que são regenerados a cada abertura). Excluir essa pasta remove todos os vestígios.

---

Comandos de navegação

openspec list

Liste mudanças ou especificações do projeto.

openspec list [options]

Opções:

Opção	Descrição
--specs	Listar especificações em vez de mudanças
--changes	Listar mudanças (padrão)
--sort <order>	Ordenar por recent (padrão) ou name
--json	Gerar saída JSON

Exemplos:

# List all active changes
openspec list

# List all specs
openspec list --specs

# JSON output for scripts
openspec list --json

Saída (texto):

Changes:
  add-dark-mode     No tasks      just now

---

openspec view

Exiba um dashboard interativo para explorar especificações e mudanças.

openspec view

Abre uma interface de terminal para navegar pelas especificações e mudanças do projeto.

---

openspec show

Exiba detalhes de uma mudança ou especificação.

openspec show [item-name] [options]

Argumentos:

Argumento	Obrigatório	Descrição
item-name	Não	Nome da mudança ou especificação (pergunta se omitido)

Opções:

Opção	Descrição
--type <type>	Especificar o tipo: change ou spec (detectado automaticamente se não houver ambiguidade)
--json	Gerar saída JSON
--no-interactive	Desabilitar prompts

Opções específicas de mudanças:

Opção	Descrição
--deltas-only	Exibir somente especificações delta (modo JSON)

Opções específicas de especificações:

Opção	Descrição
--requirements	Exibir somente requisitos, sem cenários (modo JSON)
--no-scenarios	Excluir o conteúdo dos cenários (modo JSON)
-r, --requirement <id>	Exibir um requisito específico pelo índice iniciado em 1 (modo JSON)

Exemplos:

# Interactive selection
openspec show

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

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

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

---

Comandos de validação

openspec validate

Valide a estrutura de mudanças e especificações e confira se os requisitos MODIFIED de uma mudança correspondem às especificações principais que substituiriam.

openspec validate [item-name] [options]

Uma mudança sem deltas de especificação falha na validação, a menos que seu .openspec.yaml declare skip_specs: true (para refatorações puras, ferramentas ou documentação — consulte Receita 5).

Argumentos:

Argumento	Obrigatório	Descrição
item-name	Não	Item específico a validar (pergunta se omitido)

Opções:

Opção	Descrição
--all	Validar todas as mudanças e especificações
--changes	Validar todas as mudanças
--specs	Validar todas as especificações
--archived	Validar se todas as tarefas das mudanças arquivadas foram concluídas (para lint no pre-commit)
--type <type>	Especificar o tipo quando o nome for ambíguo: change ou spec
--strict	Habilitar o modo de validação estrita
--json	Gerar saída JSON
--concurrency <n>	Máximo de validações paralelas (padrão: 6, ou variável de ambiente OPENSPEC_CONCURRENCY)
--no-interactive	Desabilitar prompts

--archived tem seu próprio escopo: não valida especificações delta (já aplicadas durante o arquivamento), mas verifica se, em cada mudança em changes/archive/, todas as caixas de seleção de tasks.md estão marcadas. Se alguma estiver desmarcada, termina com código diferente de zero. Assim, mudanças arquivadas com trabalho incompleto podem ser detectadas, por exemplo, em um hook de pre-commit.

Exemplos:

# Interactive validation
openspec validate

# Validate a specific change
openspec validate add-dark-mode

# Validate all changes
openspec validate --changes

# Validate everything with JSON output (for CI/scripts)
openspec validate --all --json

# Strict validation with increased parallelism
openspec validate --all --strict --concurrency 12

# Fail if any archived change still has unchecked tasks
openspec validate --archived

Saída (texto):

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

1 warning found

Saída (JSON):

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

---

Comandos do ciclo de vida

openspec archive

Arquive uma mudança concluída e mescle as especificações delta às principais.

openspec archive [change-name] [options]

Argumentos:

Argumento	Obrigatório	Descrição
change-name	Não	Mudança a arquivar (pergunta se omitido; obrigatório quando não houver quem responda ao prompt)

Opções:

Opção	Descrição
-y, --yes	Ignorar prompts de confirmação. Obrigatório quando não houver quem responda — AI agent, job de CI ou execução com stdin fechado
--skip-specs	Ignorar atualizações das especificações nesta execução de arquivamento. Uma mudança sem deltas permanentes deve declarar skip_specs: true no .openspec.yaml; assim, será arquivada sem essa opção
--no-validate	Ignorar a validação (exige confirmação). Também desativa a descontinuação de capacidades: sem o parecer do validador, nada é descontinuado

Exemplos:

# Interactive archive (asks which change, then confirms)
openspec archive

# Archive specific change
openspec archive add-dark-mode

# Archive without prompts (agents, CI, scripts)
openspec archive add-dark-mode --yes

# Archive a tooling change that doesn't affect specs
openspec archive update-ci-config --skip-specs

Descontinuar uma capacidade: adicione o marcador de descontinuação aos metadados da mudança:

openspec/changes/retire-legacy/.openspec.yaml

schema: spec-driven
retire_capabilities: true

Em seguida, arquive a mudança normalmente:

openspec archive retire-legacy --yes

Mantenha seus próprios metadados: uma chave de nível superior que começa com x- em minúsculas é sua. O OpenSpec nunca a lê, grava ou informa, então openspec validate --strict continua sem erros em uma mudança que tem dados específicos de uma ferramenta:

openspec/changes/add-dark-mode/.openspec.yaml

schema: spec-driven
x-tracker: SB-5497
x-jiraKey: ABC-1

O nome após o prefixo é escolha sua, em qualquer capitalização ou grafia, desde que não esteja vazio e não contenha espaços em branco. Há dois limites: o próprio prefixo é em minúsculas, então X-Tracker continua sendo informado, e as extensões são permitidas apenas no nível superior — uma chave dentro de initiative: é rejeitada, qualquer que seja o nome. Qualquer outra chave de nível superior não reconhecida continua sendo informada como sem efeito.

Quando a mudança remove o último requisito de uma capacidade, o OpenSpec exclui seu spec.md ativo. Os deltas de outras capacidades na mesma mudança ainda atualizam suas especificações principais. Sem o marcador, o arquivamento é interrompido antes de alterar arquivos e solicita que você o adicione.

O que faz:

1. Valida a mudança (a menos que --no-validate seja usado)
2. Solicita confirmação (a menos que --yes seja usado)
3. Reserva o destino do arquivo antes de alterar qualquer especificação principal
4. Valida e mescla as especificações delta ativas em openspec/specs/ — uma capacidade cujo último requisito seja removido pela mudança é descontinuada e seu arquivo de especificação é excluído, mas somente se o .openspec.yaml da mudança declarar retire_capabilities: true junto a schema:
5. Move a pasta da mudança para openspec/changes/archive/YYYY-MM-DD-<name>/
6. Se uma alteração de especificação ou a movimentação final falhar antes da conclusão do arquivamento, restaura as especificações e mantém ou devolve a mudança ao caminho ativo
7. Se uma cópia fallback verificada for concluída, mas a limpeza da origem em preparação falhar, mantém o arquivo completo e o estado confirmado das especificações para recuperação

Sem um terminal: um AI agent, job de CI ou execução com stdin fechado não consegue responder à etapa 2. Portanto, o arquivamento para antes de alterar qualquer coisa, termina com código 1 e informa o comando a repetir — openspec archive <name> --yes, mantendo as demais opções fornecidas. Passe --yes (e o nome da mudança) desde o início para evitar essa etapa.

---

Comandos de fluxo de trabalho

Estes comandos dão suporte ao fluxo OPSX orientado por artefatos. Eles são úteis tanto para pessoas que verificam o progresso quanto para agents que determinam as próximas etapas.

openspec new change

Crie um diretório de mudança e, opcionalmente, metadados versionados na raiz resolvida do OpenSpec.

openspec new change <name> [options]

Os nomes de mudanças devem usar kebab-case em letras minúsculas: letras minúsculas, números e hífens simples. Não podem conter espaços, sublinhados, letras maiúsculas, hífens consecutivos ou hífens no início/fim. É permitido começar com um número para ordenar mudanças ou indicar níveis, por exemplo, 100-add-feature ou 00001-add-auth.

Opções:

Opção	Descrição
--description <text>	Descrição a adicionar a README.md
--goal <text>	Metadados opcionais de objetivo a armazenar com a mudança
--schema <name>	Schema de fluxo de trabalho a usar
--store <id>	ID da store a usar como raiz do OpenSpec (store é um repositório OpenSpec independente que você registrou)
--json	Gerar saída JSON

Exemplos:

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

openspec status

Exiba o status de conclusão dos artefatos de uma mudança.

openspec status [options]

Opções:

Opção	Descrição
--change <id>	Nome da mudança (pergunta se omitido)
--schema <name>	Substituição do schema (detectado automaticamente na configuração da mudança)
--json	Gerar saída JSON

Exemplos:

# Interactive status check
openspec status

# Status for specific change
openspec status --change add-dark-mode

# JSON for agent use
openspec status --change add-dark-mode --json

Saída (texto):

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

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

Uma mudança que declara skip_specs: true exibe a etapa de especificações como [~] specs (skipped: change declares skip_specs) e a exclui da contagem de progresso.

Saída (JSON):

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

isPlanningComplete informa se existem todos os artefatos de planejamento não ignorados; artefatos ignorados contam como satisfeitos, mesmo sem serem criados. O campo não informa se as tarefas de implementação foram concluídas. isComplete é mantido como alias de compatibilidade com o mesmo valor.

Os artefatos são listados na ordem das dependências — uma dependência nunca aparece depois do artefato que a exige. Quando artefatos ficam prontos ao mesmo tempo (specs e design do schema spec-driven só precisam de proposal), mantêm a ordem declarada no schema, em vez da ordem alfabética. Portanto, o primeiro item ready é o próximo artefato a escrever.

---

openspec instructions

Obtenha instruções detalhadas para criar um artefato ou executar tarefas. AI agents usam esse comando para entender o que criar em seguida.

openspec instructions [artifact] [options]

Argumentos:

Argumento	Obrigatório	Descrição
artifact	Não	ID do artefato ou superfície de entrada do fluxo: apply ou archive

Opções:

Opção	Descrição
--change <id>	Nome da mudança (obrigatório no modo não interativo)
--schema <name>	Substituição do schema
--json	Gerar saída JSON

Casos especiais: use apply para obter instruções de implementação das tarefas. Use archive para consultar as entradas atuais de arquivamento, somente para leitura (context e operationGuidance), de uma mudança válida; esse comando não arquiva nem altera nada.

Exemplos:

# Get instructions for next artifact
openspec instructions --change add-dark-mode

# Get specific artifact instructions
openspec instructions design --change add-dark-mode

# Get apply/implementation instructions
openspec instructions apply --change add-dark-mode

# Get current archive operation inputs without archiving
openspec instructions archive --change add-dark-mode --json

# JSON for agent consumption
openspec instructions design --change add-dark-mode --json

A saída inclui:

• Conteúdo do template do artefato
• Contexto do projeto, proveniente da configuração
• Conteúdo dos artefatos dependentes
• Regras da configuração para cada artefato
• Contexto atual do projeto e orientações correspondentes para as operações apply/archive

As entradas da operação são lidas do repositório resolvido ou da store selecionada a cada invocação. O contexto do projeto é uma entrada obrigatória no nível do prompt: os agents o leem e aplicam os fatos, as convenções e as restrições relevantes. As orientações por operação são recomendações adicionais opcionais: os agents consideram todos os itens e seguem somente os que forem aplicáveis e compatíveis com o fluxo integrado. Ambos os campos permanecem separados das escolhas explícitas da pessoa usuária, do estado controlado pela CLI, das instruções integradas e das regras dos artefatos. Conflitos no contexto são informados; orientações conflitantes ou inaplicáveis não são seguidas, e o motivo é explicado. Esses são contratos de comportamento para agents gerados, não verificações impostas pela CLI. instructions archive retorna somente a mudança selecionada, entradas opcionais e metadados da raiz; não inclui o fluxo estático de arquivamento.

Para um artefato ignorado por skip_specs: true, a saída contém somente um aviso (JSON adiciona os campos skipped/warning); o artefato não deve ser criado.

---

openspec templates

Exiba os caminhos resolvidos dos templates para todos os artefatos de um schema.

openspec templates [options]

Opções:

Opção	Descrição
--schema <name>	Schema a inspecionar (padrão: spec-driven)
--json	Gerar saída JSON

Exemplos:

# Show template paths for default schema
openspec templates

# Show templates for custom schema
openspec templates --schema my-workflow

# JSON for programmatic use
openspec templates --json

Saída (texto):

Schema: spec-driven

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

---

openspec schemas

Liste os schemas de fluxo de trabalho disponíveis, com suas descrições e sequências de artefatos.

openspec schemas [options]

Opções:

Opção	Descrição
--json	Gerar saída JSON
--store <id>	Usar uma store registrada como raiz do OpenSpec

Exemplo:

openspec schemas

Saída:

Available schemas:

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

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

---

Comandos de schema

Comandos para criar e gerenciar schemas de fluxos de trabalho personalizados.

openspec schema init

Crie um novo schema local ao projeto.

openspec schema init <name> [options]

Argumentos:

Argumento	Obrigatório	Descrição
name	Sim	Nome do schema (kebab-case)

Opções:

Opção	Descrição
--description <text>	Descrição do schema
--artifacts <list>	IDs de artefato separados por vírgulas (padrão: proposal,specs,design,tasks)
--default	Definir como schema padrão do projeto
--no-default	Não perguntar se deve ser definido como padrão
--force	Sobrescrever o schema existente
--json	Gerar saída JSON

Exemplos:

# Interactive schema creation
openspec schema init research-first

# Non-interactive with specific artifacts
openspec schema init rapid \
  --description "Rapid iteration workflow" \
  --artifacts "proposal,tasks" \
  --default

O que cria:

openspec/schemas/<name>/
├── schema.yaml           # Schema definition
└── templates/
    ├── proposal.md       # Template for each artifact
    ├── specs.md
    ├── design.md
    └── tasks.md

---

openspec schema fork

Copie um schema existente para o projeto e personalize-o.

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

Argumentos:

Argumento	Obrigatório	Descrição
source	Sim	Schema a copiar
name	Não	Nome do novo schema (padrão: <source>-custom)

Opções:

Opção	Descrição
--force	Sobrescrever o destino existente
--json	Gerar saída JSON

Exemplo:

# Fork the built-in spec-driven schema
openspec schema fork spec-driven my-workflow

---

openspec schema validate

Valide a estrutura e os templates de um schema.

openspec schema validate [name] [options]

Argumentos:

Argumento	Obrigatório	Descrição
name	Não	Schema a validar (valida todos se omitido)

Opções:

Opção	Descrição
--verbose	Exibir etapas detalhadas da validação
--json	Gerar saída JSON

Exemplo:

# Validate a specific schema
openspec schema validate my-workflow

# Validate all schemas
openspec schema validate

---

openspec schema which

Exiba de onde vem a resolução de um schema (útil para depurar a precedência).

openspec schema which [name] [options]

Argumentos:

Argumento	Obrigatório	Descrição
name	Não	Nome do schema

Opções:

Opção	Descrição
--all	Listar todos os schemas e suas origens
--json	Gerar saída JSON

Exemplo:

# Check where a schema comes from
openspec schema which spec-driven

Saída:

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

Precedência dos schemas:

1. Projeto: openspec/schemas/<name>/
2. Usuário: ~/.local/share/openspec/schemas/<name>/
3. Pacote: schemas integrados

---

Comandos de configuração

openspec config

Consulte e modifique a configuração global do OpenSpec.

openspec config <subcommand> [options]

Subcomandos:

Subcomando	Descrição
path	Exibir o local do arquivo de configuração
list	Exibir todas as configurações atuais
get <key>	Obter um valor específico
set <key> <value>	Definir um valor
unset <key>	Remover uma chave
reset	Restaurar os valores padrão
edit	Abrir no $EDITOR
profile [preset]	Configurar o profile do fluxo de trabalho interativamente ou por predefinição

Exemplos:

# Show config file path
openspec config path

# List all settings
openspec config list

# Get a specific value
openspec config get telemetry.enabled

# Set a value (disable anonymous usage telemetry)
openspec config set telemetry.enabled false

# Set a string value explicitly
openspec config set user.name "My Name" --string

# Remove a custom setting
openspec config unset user.name

# Set a machine-level default store (fallback root when no --store,
# local root, or project store: pointer resolves)
openspec config set defaultStore team-plans

# Reset all configuration
openspec config reset --all --yes

# Edit config in your editor
openspec config edit

# Configure profile with action-based wizard
openspec config profile

# Fast preset: switch workflows to core (keeps delivery mode)
openspec config profile core

Desativar a telemetria: telemetry.enabled fica habilitada por padrão quando não está definida (modelo de desativação opcional). Defina-a como false para desabilitar as estatísticas anônimas de uso e a verificação de versão de openspec update. As variáveis de ambiente têm prioridade sobre a configuração: OPENSPEC_TELEMETRY=0, DO_NOT_TRACK=1 e um valor verdadeiro de CI (por exemplo, true/1/yes) sempre desabilitam a telemetria, independentemente do valor configurado.

openspec config profile começa com um resumo do estado atual e permite escolher:

• Alterar a distribuição e os fluxos de trabalho
• Alterar somente a distribuição
• Alterar somente os fluxos de trabalho
• Manter as configurações atuais (sair)

Se você mantiver as configurações atuais, nenhuma alteração será gravada e nenhum prompt de atualização será exibido. Se não houver alterações de configuração, mas os arquivos atuais do projeto estiverem fora de sincronia com o profile/distribuição global, o OpenSpec exibirá um aviso e sugerirá openspec update. Pressionar Ctrl+C também cancela o fluxo sem problemas (sem stack trace) e encerra com o código 130. Na lista de verificação dos fluxos, [x] significa que o fluxo está selecionado na configuração global. Para aplicar essas seleções aos arquivos do projeto, execute openspec update (ou escolha Apply changes to this project now? quando essa pergunta for exibida dentro de um projeto).

Exemplos interativos:

# Delivery-only update
openspec config profile
# choose: Change delivery only
# choose delivery: Skills only

# Workflows-only update
openspec config profile
# choose: Change workflows only
# toggle workflows in the checklist, then confirm

---

Comandos utilitários

openspec feedback

Envie comentários sobre o OpenSpec. O comando cria uma issue no GitHub.

openspec feedback <message> [options]

Argumentos:

Argumento	Obrigatório	Descrição
message	Sim	Resumo dos comentários; textos longos são reduzidos no título da issue e preservados no corpo

Opções:

Opção	Descrição
--body <text>	Detalhes adicionais incluídos após o resumo

Requisitos: a CLI do GitHub (gh) precisa estar instalada e autenticada.

Exemplo:

openspec feedback "Add support for custom artifact types" \
  --body "I'd like to define my own artifact types beyond the built-in ones."

---

openspec completion

Gerencie as conclusões de comandos do shell para a CLI do OpenSpec.

openspec completion <subcommand> [shell]

Subcomandos:

Subcomando	Descrição
generate [shell]	Enviar o script de conclusão para stdout
install [shell]	Instalar conclusões para o shell
uninstall [shell]	Remover as conclusões instaladas

Shells compatíveis: bash, zsh, fish, powershell

Exemplos:

# Install completions (auto-detects shell)
openspec completion install

# Install for specific shell
openspec completion install zsh

# Generate script for manual installation (bash)
openspec completion generate bash > ~/.bash_completion.d/openspec

# Uninstall
openspec completion uninstall

Windows (PowerShell): instale conclusões no host atual do PowerShell:

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

$env:PROFILE informa ao OpenSpec qual perfil configurar nesta sessão. O instalador cria os diretórios de perfil ausentes e adiciona um bloco gerenciado que carrega OpenSpecCompletion.ps1. Recarregue o perfil para habilitar as conclusões imediatamente.

Para desinstalar do host atual, execute:

$env:PROFILE = $PROFILE
openspec completion uninstall powershell

Reinicie o PowerShell após a desinstalação para remover as conclusões da sessão atual.

As conclusões são opt-in. A CLI as menciona uma vez em stderr, na primeira execução de um comando em um terminal interativo, e não volta a exibir essa mensagem — ela também permanece silenciosa se as conclusões já estiverem instaladas. Defina OPENSPEC_NO_COMPLETIONS=1 para suprimir completamente essa sugestão.

---

Códigos de saída

Código	Significado
0	Sucesso
1	Erro (falha de validação, arquivos ausentes etc.)

---

Variáveis de ambiente

Variável	Descrição
OPENSPEC_TELEMETRY	Defina como 0 para desativar a telemetria e a verificação de versão de openspec update (substitui telemetry.enabled na configuração global)
DO_NOT_TRACK	Defina como 1 para desativar a telemetria e a verificação de versão de openspec update (sinal DNT padrão; substitui a configuração)
OPENSPEC_CONCURRENCY	Concorrência padrão para validação em lote (padrão: 6)
EDITOR ou VISUAL	Editor de openspec config edit
NO_COLOR	Desabilita as cores da saída quando definida
OPENSPEC_NO_ANIMATION	Desabilita a animação de boas-vindas de openspec init quando definida
OPENSPEC_NO_COMPLETIONS	Defina como 1 para suprimir a sugestão única sobre conclusões do shell
OPENSPEC_NO_UPDATE_CHECK	Desabilita a verificação de uma CLI publicada mais recente por openspec update quando definida (qualquer valor, inclusive vazio). A verificação também é ignorada quando CI está definido (exceto false/0/no/off) ou quando NODE_ENV=test
npm_config_registry	Registro consultado pela verificação de versão de openspec update. Precisa ser uma URL http(s); caso contrário, usa https://registry.npmjs.org. Nenhum arquivo .npmrc é lido

---

Documentação relacionada

• Comandos — comandos de barra para IA (/opsx:propose, /opsx:apply etc.)
• Fluxos de trabalho — padrões comuns e quando usar cada comando
• Personalização — criar schemas e templates personalizados
• Primeiros passos — guia de configuração inicial