Referência da CLI

A CLI do OpenSpec (openspec) fornece comandos de terminal para configuração de projeto, validação, inspeção de status e gerenciamento. Esses comandos complementam os comandos de barra de IA (como /opsx:propose) documentados em Comandos.

Resumo

Categoria	Comandos	Propósito
Configuração	`init`, `update`	Inicializa e atualiza o OpenSpec no seu projeto
Repositórios (repos OpenSpec independentes)	`store setup`, `store register`, `store unregister`, `store remove`, `store list`, `store doctor`	Gerenciar repositórios — repos OpenSpec independentes que você registrou
Saúde	`doctor`	Relatar a saúde do relacionamento para a raiz resolvida
Contexto de trabalho	`context`	Montar o conjunto de trabalho (raiz + repositórios referenciados)
Conjuntos de trabalho pessoais	`workset create`, `workset list`, `workset open`, `workset remove`	Manter e abrir visualizações de trabalho pessoais e locais na sua ferramenta
Navegação	`list`, `view`, `show`	Explorar alterações e especificações
Validação	`validate`	Verificar alterações e especificações quanto a problemas
Ciclo de vida	`archive`	Finalizar alterações concluídas
Fluxo de trabalho	`new change`, `status`, `instructions`, `templates`, `schemas`	Suporte a fluxo de trabalho orientado por artefatos
Esquemas	`schema init`, `schema fork`, `schema validate`, `schema which`	Criar e gerenciar fluxos de trabalho personalizados
Configuração	`config`	Visualizar e modificar configurações
Utilitário	`feedback`, `completion`	Feedback e integração com shell

Comandos para Humanos vs Agentes

A maioria dos comandos de CLI é projetada para uso humano em um terminal. Alguns comandos também suportam uso por agentes/scripts por meio de saída em JSON.

Comandos Exclusivos para Humanos

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

Comando	Propósito
`openspec init`	Inicializar projeto (prompts interativos)
`openspec view`	Painel interativo
`openspec workset open <name>`	Abrir um workset salvo (janela do editor ou sessão de agente no terminal)
`openspec config edit`	Abrir configuração no editor
`openspec feedback`	Enviar feedback via GitHub
`openspec completion install`	Instalar completions de shell

Comandos Compatíveis com Agentes

Estes comandos suportam saída --json para uso programático por agentes de IA e scripts:

Comando	Uso Humano	Uso por Agente
`openspec list`	Navegar por mudanças/specs	`--json` para dados estruturados
`openspec show <item>`	Ler conteúdo	`--json` para parsing
`openspec validate`	Verificar problemas	`--all --json` para validação em lote
`openspec status`	Ver progresso de artefatos	`--json` para status estruturado
`openspec instructions`	Obter próximos passos	`--json` para instruções do agente
`openspec templates`	Encontrar caminhos de templates	`--json` para resolução de caminhos
`openspec schemas`	Listar schemas disponíveis	`--json` para descoberta de schemas; `--store <id>` para selecionar uma raiz registrada
`openspec store setup <id>`	Criar e registrar um store local	`--json` com entradas explícitas para saída estruturada de configuração
`openspec store register <path>`	Registrar um store existente	`--json` para saída estruturada de registro
`openspec store unregister <id>`	Esquecer um registro de store local	`--json` para saída estruturada de limpeza
`openspec store remove <id>`	Excluir uma pasta de store local registrada	`--yes --json` para exclusão não interativa
`openspec store list`	Navegar por stores registrados	`--json` para registros estruturados
`openspec store doctor`	Verificar configuração de store local	`--json` para diagnósticos estruturados
`openspec new change <id>`	Criar scaffolding de mudança local ao repositório	`--json`, além de `--store <id>` para usar um store registrado como raiz do OpenSpec
`openspec workset create [name]`	Compor uma visão de trabalho pessoal	`--member <path> --json` para composição não interativa
`openspec workset list`	Navegar por worksets salvos	`--json` para visões estruturadas
`openspec workset remove <name>`	Excluir uma visão salva	`--yes --json` para remoção não interativa

Opções Globais

Estas opções funcionam com todos os comandos:

Opção	Descrição
`--version`, `-V`	Mostrar número da versão
`--no-color`	Desativar saída com cores
`--help`, `-h`	Exibir ajuda para o comando

Comandos de Configuração

`openspec init`

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

O comportamento padrão usa os valores padrão da configuração global: perfil core, entrega both, workflows 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 novo projeto. Para um projeto existente, edite o campo context da configuração para que o OpenSpec nunca sobrescreva 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 de forma não interativa. Use `all`, `none` ou lista separada por vírgulas
`--language <language>`	Escrever artefatos neste idioma ao criar uma nova configuração
`--force`	Limpeza automática de arquivos legados sem prompt
`--profile <profile>`	Substituir o perfil global para esta execução de init (`core` ou `custom`)
`--no-animation`	Exibir uma tela de boas-vindas estática em vez da animada
`--copilot-cloud`	Configurar arquivos de coding-agent em nuvem do GitHub Copilot cloud coding-agent files sem prompt
`--no-copilot-cloud`	Pular arquivos de coding-agent em nuvem do GitHub Copilot sem prompt

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

A animação de boas-vindas também é pulada quando a variável de ambiente OPENSPEC_NO_ANIMATION está definida (qualquer valor, incluindo vazio), quando NO_COLOR está definida para um valor não vazio, ou quando a preferência de movimento reduzido do SO está ativada (Reduce Motion no macOS, animações desativadas no GNOME).

IDs de ferramentas suportados (--tools) — windsurf também é aceito, como alias para 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 espelha AI_TOOLS em src/core/config.ts. Veja Ferramentas Suportadas para os caminhos de skills e comandos de cada ferramenta.

Exemplos:

bash

# Inicialização interativa
openspec init

# Inicializar em um diretório específico
openspec init ./my-project

# Não interativo: configurar para Claude e Cursor
openspec init --tools claude,cursor

# Não interativo: configurar skills globais do MiniMax Code
openspec init --tools minimax-code

# Configurar para todas as ferramentas suportadas
openspec init --tools all

# Substituir perfil para esta execução
openspec init --profile core

# Pular prompts e limpar arquivos legados automaticamente
openspec init --force

O que ele cria:

openspec/
├── specs/              # Suas especificações (fonte de verdade)
├── changes/            # Mudanças propostas
└── config.yaml         # Configuração do projeto

.claude/skills/         # Skills do Claude Code (se claude selecionado)
.cursor/skills/         # Skills do Cursor (se cursor selecionado)
.cursor/commands/       # Comandos OPSX do Cursor (se a entrega inclui commands)
.agents/skills/         # Skills compartilhados para ferramentas compatíveis com AGENTS.md (se agents selecionado)
... (outras configurações de ferramentas)

`openspec update`

Atualiza os arquivos de instruções do OpenSpec após atualizar o CLI. Regenera os arquivos de configuração das ferramentas de IA usando seu perfil global atual, workflows selecionados e modo de entrega.

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 atualização mesmo quando os arquivos estão atualizados

Exemplo:

bash

# Atualizar arquivos de instruções após upgrade do npm
npm install -g @fission-ai/openspec@latest
openspec update

Atualize o pacote primeiro. Os arquivos de instruções são gerados pelo CLI instalado, então executar openspec update contra uma instalação desatualizada reporta tudo como atualizado sem adicionar os workflows que as versões mais novas trazem.

Para tornar isso visível, openspec update consulta o registro npm para verificar se um CLI mais novo foi publicado. Quando o seu está desatualizado, ele oferece fazer o upgrade:

text

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)

Responda sim e ele executa npm install -g @fission-ai/openspec@latest, depois reexecuta a atualização com o novo CLI para que os novos workflows sejam aplicados no mesmo comando. Ele confirma o upgrade perguntando ao binário instalado sua versão em vez de confiar no código de saída do npm, então se outra instalação mais cedo na sua PATH ainda estiver respondendo, ele informa em vez de declarar sucesso. Responda não e ele imprime o comando e atualiza com o CLI que você tem. Ctrl-C interrompe o comando.

A oferta aparece apenas em um terminal interativo e apenas quando o npm é o dono da instalação — o único caso em que npm install -g realmente resolve. Tudo o mais recebe o comando que corresponde à forma como foi instalado:

Como o OpenSpec está instalado	O que você recebe
Instalação global via npm	O prompt, e o upgrade é executado para você — em um terminal interativo; saída redirecionada recebe o comando impresso
Instalação global via pnpm, bun, yarn ou volta	O próprio comando daquele gerenciador: `pnpm add -g …@latest`, `bun add -g …@latest`, `yarn global add …@latest` ou `volta install …@latest`
Uma dependência do projeto	Uma nota para atualizar a dependência, já que o gerenciador de pacotes do projeto controla o lockfile
Um cache de `npx` / `dlx`	`npx @fission-ai/openspec@latest update` — esse comando é a atualização, então não há segundo passo
Um clone git	Nada — sua versão é o que o branch diz

Sempre que algo é impresso, ele indica o diretório de onde o CLI em execução foi carregado — a coisa a verificar quando você fez o upgrade mas um shim desatualizado ainda controla sua PATH.

Ele consulta o registro em npm_config_registry quando o npm exporta essa variável, e https://registry.npmjs.org caso contrário. Nenhum .npmrc é lido: deixar o conteúdo de arquivos escolher para onde uma requisição externa vai é um fluxo que vale a pena evitar, e o .npmrc de um projeto viaja com o repositório. Em um espelho privado, exporte npm_config_registry — ou defina OPENSPEC_NO_UPDATE_CHECK para pular a verificação completamente. A verificação é pulada quando CI está definida para qualquer valor que não seja um valor explícito de desativação (false, 0, no, off ou vazio), sob NODE_ENV=test, e sempre que OPENSPEC_NO_UPDATE_CHECK (qualquer valor), DO_NOT_TRACK=1 ou OPENSPEC_TELEMETRY=0 estiver definido. Ela roda antes da atualização e pode atrasá-la em no máximo 1,5 segundos — ela desiste após esse tempo mesmo quando a rede perde pacotes silenciosamente, e fica silenciosa quando o registro é inacessível.

Como "atualizado" é decidido: os arquivos de skills registram a versão que os gerou, então o OpenSpec compara isso com o CLI instalado. Os arquivos de comandos não carregam carimbo de versão, então para uma ferramenta que tem comandos mas não skills (entrega commands), o OpenSpec compara o conteúdo dos arquivos com o que ele geraria agora — edições nesses arquivos contam como divergência e são sobrescritas. Com entrega skills ou both, apenas a versão registrada é verificada, então um arquivo editado manualmente cuja versão ainda corresponde é deixado como está; use --force para reescrevê-lo. De qualquer forma, arquivos gerados são propriedade do OpenSpec — mantenha suas próprias instruções em outro lugar.

Stores (repositórios OpenSpec independentes)

Beta. Stores e os recursos construídos sobre eles (referências, contexto de trabalho, conjuntos de trabalho) são novos; nomes de comandos, flags, formatos de arquivo e saída JSON podem mudar entre versões. Para um guia orientado a problemas, consulte o guia de stores.

Uma store é um repositório OpenSpec independente que você registrou nesta máquina — por exemplo, um repositório de planejamento ou um repositório de contratos. Registrar uma store permite que comandos normais (list, show, status, validate, new change, archive, ...) atuem nela a partir de qualquer lugar, passando --store <id>.

`openspec store setup`

Cria e registra uma store local. Sem argumentos em um terminal, o OpenSpec guia o usuário pelo processo de configuração. Agentes e scripts devem passar entradas explícitas e usar --json.

bash

openspec store setup [id] [opções]

Opções:

Opção	Descrição
`--path <caminho>`	Pasta onde a store deve ficar (por exemplo, `~/openspec/<id>`)
`--remote <url>`	Grava o remoto canônico no `store.yaml` da nova store
`--init-git`	Inicializa um repositório Git com um commit inicial (padrão)
`--no-init-git`	Ignora toda ação do Git: sem init, sem commit inicial
`--json`	Saída JSON

Execuções não interativas (--json, scripts, agentes) devem passar tanto o id da store quanto --path. Em um terminal interativo, o setup solicita a localização com uma sugestão editável em um lugar visível e de propriedade do usuário (por exemplo, ~/openspec/<id>); nunca usa como padrão o diretório de dados gerenciado do OpenSpec.

Exemplos:

bash

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`

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

bash

openspec store register [caminho] [opções]

Opções:

Opção	Descrição
`--id <id>`	Id da store; usa o padrão dos metadados da store ou do nome da pasta
`--yes`	Confirma a criação dos metadados de identidade da store para uma raiz OpenSpec saudável
`--json`	Saída JSON

`openspec store unregister`

Esquece um registro de store local sem excluir arquivos.

bash

openspec store unregister <id> [--json]

Use isto quando uma store foi movida, clonada em outro lugar ou não deve mais ser exibida pelo OpenSpec nesta máquina.

`openspec store remove`

Esquece um registro de store local e exclui sua pasta local.

bash

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

remove mostra a pasta exata antes de excluir em um terminal interativo. Agentes, scripts e chamadas JSON devem passar --yes para confirmar a exclusão. O OpenSpec se recusa a excluir uma pasta que não contenha metadados de store correspondentes.

`openspec store list`

Lista as stores registradas localmente.

bash

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

`openspec store doctor`

Verifica o registro de store local, metadados e presença do Git.

bash

openspec store doctor [id] [--json]

O doctor é somente diagnóstico; ele relata raízes ausentes, incompatibilidades de metadados e estado inválido do registro local sem modificar a store.

Referenciando stores a partir de um projeto

Um repositório de projeto pode declarar em openspec/config.yaml quais stores seu trabalho utiliza:

yaml

schema: spec-driven
references:
  - team-context

A partir de então, a saída de openspec instructions nesse repositório (tanto nas superfícies por artefato quanto em apply, modos JSON e humano) traz um índice das especificações de cada store referenciada — ids de spec, um resumo de uma linha da seção Purpose de cada spec e o comando de busca (openspec show <spec-id> --type spec --store <id>). O índice é construído ao vivo a partir do checkout registrado em cada execução; o conteúdo das especificações nunca é copiado para a saída.

Referências são contexto somente leitura. Elas nunca mudam onde os comandos atuam: o trabalho permanece na raiz do próprio repositório, e escrever em uma store referenciada continua sendo uma ação explícita com --store. Uma referência que não pode ser resolvida (por exemplo, uma store não registrada nesta máquina) se degrada para um aviso no índice com a correção exata, e as instruções ainda são geradas. openspec doctor relata a saúde das referências em um só lugar.

Gravando de onde uma store foi clonada

Uma store pode gravar sua origem canônica de clone em seu arquivo de identidade commitado, para que a integração nunca termine em "registre a store":

bash

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

O remoto vai para .openspec-store/store.yaml dentro do commit inicial, então todo clone já nasce sabendo disso. Para uma store existente, edite store.yaml manualmente e faça commit. store doctor mostra o remoto gravado (e a origem Git observada no checkout); as orientações de setup/register mencionam isso; e register grava a origem do checkout no registro local da máquina.

Uma declaração de referência também pode carregar a origem do clone, para que um colega que ainda não tem a store receba uma correção completa e copiável (git clone <remote> <caminho> && openspec store register <caminho> --id <id>):

yaml

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

Gravar um remoto não é sincronização: o OpenSpec nunca clona, puxa ou envia por conta própria.

Declarando uma store padrão

Um repositório cujo planejamento é totalmente externalizado — sem openspec/specs/ ou openspec/changes/ locais — pode declarar sua store uma única vez em vez de passar --store em todo comando:

yaml

# openspec/config.yaml (o único arquivo sob openspec/)
store: team-context

Os comandos normais então resolvem automaticamente para a store declarada; o banner da raiz e o bloco root em JSON relatam source: "declared" com o id da store, e as dicas impressas ainda carregam --store <id>. A declaração é um fallback, nunca uma substituição: --store explícito sempre vence, e um diretório com pastas reais de planejamento ignora o ponteiro (com um aviso). Para converter um repositório ponteiro em uma raiz OpenSpec local, remova a linha store: e execute openspec init — init se recusa a criar a estrutura enquanto a declaração estiver presente.

Uma variante a nível de máquina cobre todos os repositórios de uma vez: openspec config set defaultStore <id> (veja Configuração). Ela é consultada somente depois que --store, uma raiz local e um ponteiro de projeto falharam em resolver; o banner da raiz e o bloco root em JSON então relatam source: "global_default".

Doctor (saúde do relacionamento)

Uma única pergunta somente leitura, em um só lugar: a raiz do OpenSpec está saudável e os repositórios que ela referencia estão disponíveis nesta máquina?

bash

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

O relatório separa a saúde da raiz, a saúde dos metadados do repositório (incluindo uma nota quando o remoto registrado e a origem do checkout divergem, e uma nota quando o checkout do repositório ficou para trás em relação à sua referência de rastreamento upstream buscada pela última vez) e a saúde das referências (as mesmas instruções de diagnóstico são exibidas, com correções de clone para referências não resolvidas). Achados de saúde de qualquer gravidade retornam código de saída 0 — agentes leem os arrays status; apenas falhas de comando (sem raiz, repositório desconhecido) retornam 1. O Doctor nunca clona, sincroniza ou repara. Para obter o conjunto montado em si, em vez de sua saúde, use openspec context.

Contexto de trabalho (o conjunto montado)

Tudo o que este trabalho relaciona por meio de declarações do OpenSpec, em um único conjunto de trabalho: a raiz do OpenSpec e os repositórios que ela referencia.

bash

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

O resumo em JSON é consumível por agentes (cada repositório referenciado disponível carrega sua receita de busca; membros não resolvidos carregam as mesmas instruções de correção e mostram o doctor). --code-workspace também grava um arquivo de workspace do VS Code contendo a raiz mais os repositórios referenciados disponíveis (ref:<id> pastas) — a única gravação que este comando realiza, recusada sem --force se o arquivo já existir. Membros indisponíveis são relatados, nunca supostos.

"Contexto de trabalho" é o conjunto montado; o campo context: em openspec/config.yaml é o contexto do projeto injetado nas instruções — duas coisas diferentes. openspec doctor responde se o conjunto está saudável; openspec context responde o que o conjunto é.

Conjuntos de trabalho pessoais

Beta. Os worksets fazem parte da nova superfície beta; comandos, sinalizadores e formatos de arquivo podem mudar entre versões. Para o tutorial passo a passo, consulte o guia de repositórios.

Um workset é uma visualização pessoal e nomeada das pastas em que você trabalha juntas — uma raiz de planejamento mais tudo o mais que você escolher — mantida na sua máquina e reaberta por nome na sua ferramenta. É puramente local: nunca é comprometido, nunca é compartilhado, nunca é derivado de declarações e remover um nunca toca uma pasta membro.

bash

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 curto (ou aceita sinalizadores --member de forma não interativa; o primeiro membro é o primário — as sessões começam nele). open inicia a ferramenta escolhida: editores (VS Code, Cursor) abrem uma janela com todos os membros e retornam; agentes de CLI (Claude Code, codex) assumem este terminal como uma sessão com todos os membros anexados e sem prompt pré-preenchido, terminando quando você sai. Uma pasta membro ausente no momento da abertura é ignorada com uma nota; o restante é aberto. A preferência de ferramenta salva pode ser substituída por abertura com --tool.

Suportar uma nova ferramenta é configuração, não código. Cada ferramenta é de um dos dois estilos de lançamento — workspace-file (lançado com o .code-workspace gerado) ou attach-dirs (um sinalizador de anexo por membro) — e a chave openers no config.json global (abra-o com openspec config edit) adiciona ferramentas ou ajusta as internas por campo:

json

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

Todo o estado do workset vive sob a pasta worksets/ do diretório de dados global (as visualizações salvas mais os arquivos <name>.code-workspace gerados, regenerados a cada abertura); excluir essa pasta remove todo o rastro.

Comandos de Navegação

`openspec list`

Liste alterações ou especificações no seu projeto.

openspec list [options]

Opções:

Opção	Descrição
`--specs`	Liste especificações em vez de alterações
`--changes`	Liste alterações (padrão)
`--sort <order>`	Ordene por `recent` (padrão) ou `name`
`--json`	Saída como JSON

Exemplos:

bash

# Listar todas as alterações ativas
openspec list

# Listar todas as especificações
openspec list --specs

# Saída JSON para scripts
openspec list --json

Saída (texto):

Changes:
  add-dark-mode     No tasks      just now

`openspec view`

Exiba um painel interativo para explorar especificações e alterações.

openspec view

Abre uma interface baseada em terminal para navegar pelas especificações e alterações do seu projeto.

`openspec show`

Exiba detalhes de uma alteração ou especificação.

openspec show [item-name] [options]

Argumentos:

Argumento	Obrigatório	Descrição
`item-name`	Não	Nome da alteração ou especificação (solicita se omitido)

Opções:

Opção	Descrição
`--type <type>`	Especifique o tipo: `change` ou `spec` (detectado automaticamente se inequívoco)
`--json`	Saída como JSON
`--no-interactive`	Desabilitar prompts

Opções específicas de alteração:

Opção	Descrição
`--deltas-only`	Mostrar apenas especificações delta (modo JSON)

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

Opção	Descrição
`--requirements`	Mostrar apenas requisitos, exclua cenários (modo JSON)
`--no-scenarios`	Excluir conteúdo de cenários (modo JSON)
`-r, --requirement <id>`	Mostrar requisito específico pelo índice baseado em 1 (modo JSON)

Exemplos:

bash

# Seleção interativa
openspec show

# Mostrar uma alteração específica
openspec show add-dark-mode

# Mostrar uma especificação específica
openspec show auth --type spec

# Saída JSON para análise
openspec show add-dark-mode --json

Comandos de Validação

`openspec validate`

Valida mudanças e especificações quanto a problemas estruturais e verifica os requisitos MODIFIED de uma mudança em relação às especificações principais que ela substituiria.

openspec validate [item-name] [options]

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

Argumentos:

Argumento	Obrigatório	Descrição
`item-name`	Não	Item específico para validar (solicita entrada se omitido)

Opções:

Opção	Descrição
`--all`	Valida todas as mudanças e especificações
`--changes`	Valida todas as mudanças
`--specs`	Valida todas as especificações
`--archived`	Valida que mudanças arquivadas tenham todas as tarefas concluídas (para linting pré-commit)
`--type <type>`	Especifica o tipo quando o nome é ambíguo: `change` ou `spec`
`--strict`	Ativa o modo de validação estrita
`--json`	Saída em JSON
`--concurrency <n>`	Máximo de validações paralelas (padrão: 6, ou variável de ambiente `OPENSPEC_CONCURRENCY`)
`--no-interactive`	Desativa solicitações de entrada

--archived tem seu próprio escopo: não valida deltas de especificação (já aplicados no momento do arquivamento), verifica que cada mudança sob changes/archive/ tenha todas as caixas de seleção em tasks.md marcadas, saindo com código não-zero se alguma estiver desmarcada. Isso detecta mudanças que foram arquivadas com trabalho inacabado — útil em um hook pré-commit.

Exemplos:

bash

# Validação interativa
openspec validate

# Validar uma mudança específica
openspec validate add-dark-mode

# Validar todas as mudanças
openspec validate --changes

# Validar tudo com saída em JSON (para CI/scripts)
openspec validate --all --json

# Validação estrita com paralelismo aumentado
openspec validate --all --strict --concurrency 12

# Falhar se alguma mudança arquivada ainda tiver tarefas desmarcadas
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):

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 de Ciclo de Vida

`openspec archive`

Arquivar uma mudança concluída e mesclar as especificações delta nas especificações principais.

openspec archive [change-name] [options]

Argumentos:

Argumento	Obrigatório	Descrição
`change-name`	Não	Mudança para arquivar (solicita entrada if omitido; obrigatório quando nada pode responder à solicitação)

Opções:

Opção	Descrição
`-y, --yes`	Pula solicitações de confirmação. Obrigatório quando nada pode respondê-las — um agente de IA, um job de CI ou qualquer execução com stdin fechado
`--skip-specs`	Pula atualizações de especificação para uma execução de arquivamento. Uma mudança que permanentemente não tem deltas de especificação deve declarar `skip_specs: true` em seu `.openspec.yaml` — ela é arquivada sem nenhuma flag
`--no-validate`	Pula a validação (requer confirmação). Também desativa a aposentadoria de capacidades — sem veredito do validador, nada é aposentado

Exemplos:

bash

# Arquivamento interativo (pergunta qual mudança e então confirma)
openspec archive

# Arquivar mudança específica
openspec archive add-dark-mode

# Arquivar sem solicitações (agentes, CI, scripts)
openspec archive add-dark-mode --yes

# Arquivar uma mudança de ferramentas que não afeta especificações
openspec archive update-ci-config --skip-specs

Aposentar uma capacidade: Adicione o marcador de aposentadoria aos metadados da mudança:

yaml

# openspec/changes/retire-legacy/.openspec.yaml
schema: spec-driven
retire_capabilities: true

Então arquive a mudança normalmente:

bash

openspec archive retire-legacy --yes

Quando a mudança remove o último requisito da capacidade, o OpenSpec exclui seu spec.md ativo. Outros deltas de capacidade na mesma mudança ainda atualizam suas especificações principais. Sem o marcador, o arquivamento para antes de alterar qualquer arquivo e informa que você deve adicioná-lo.

O que ele faz:

Valida a mudança (a menos que --no-validate)
Solicita confirmação (a menos que --yes)
Reserva o destino de arquivamento antes de alterar qualquer especificação principal
Valida e mescla as especificações delta ativas em openspec/specs/ — uma capacidade cujo último requisito a mudança remove é aposentada e seu arquivo de especificação excluído, mas apenas quando o .openspec.yaml da mudança declara retire_capabilities: true ao lado de seu schema:
Move a pasta da mudança para openspec/changes/archive/YYYY-MM-DD-<name>/
Se uma mutação de especificação ou o movimento final falhar antes de um arquivamento completo ser garantido, restaura as especificações e deixa ou retorna a mudança em seu caminho ativo
Se uma cópia de fallback verificada for concluída mas a limpeza da fonte estagiada falhar, retém o arquivamento completo e o estado de especificação commitado para recuperação

Sem um terminal: um agente de IA, um job de CI ou qualquer execução com stdin fechado não pode responder à etapa 2, então o arquivamento para antes de tocar em qualquer coisa, sai com código 1 e informa o comando para reexecutar — openspec archive <name> --yes, com quaisquer outras flags que você passou. Passe --yes (e o nome da mudança) desde o início para evitar a ida e volta.

Comandos de Workflow

Esses comandos dão suporte ao workflow OPSX orientado a artefatos. São úteis tanto para humanos verificarem o progresso quanto para agentes determinarem os próximos passos.

`openspec new change`

Cria um diretório de mudança e metadados opcionais versionados na raiz resolvida do OpenSpec.

bash

openspec new change <nome> [opções]

Os nomes de mudanças devem usar kebab-case minúsculo: letras minúsculas, números e hifens simples. Não podem conter espaços, underscores, letras maiúsculas, hifens consecutivos ou hifens no início ou no final. É permitido um número inicial, para que você possa prefixar nomes para ordenar ou hierarquizar mudanças, por exemplo 100-add-feature ou 00001-add-auth.

Opções:

Opção	Descrição
`--description <texto>`	Descrição a ser adicionada ao `index.md`
`--goal <texto>`	Metadados de objetivo opcionais para armazenar com a mudança
`--schema <nome>`	Schema de workflow a ser utilizado
`--store <id>`	ID do store a ser usado como raiz do OpenSpec (um store é um repositório OpenSpec independente que você registrou)
`--json`	Saída em JSON

Exemplos:

bash

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

`openspec status`

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

openspec status [opções]

Opções:

Opção	Descrição
`--change <id>`	Nome da mudança (solicita se omitido)
`--schema <nome>`	Substituição do schema (detectado automaticamente pela configuração da mudança)
`--json`	Saída em JSON

Exemplos:

bash

# Verificação interativa de status
openspec status

# Status para uma mudança específica
openspec status --change add-dark-mode

# JSON para uso por agentes
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 declare skip_specs: true mostra seu estágio de specs como [~] specs (skipped: change declares skip_specs) e o exclui da contagem de progresso.

Saída (JSON):

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 todos os artefatos de planejamento não ignorados existem; artefatos ignorados são considerados satisfeitos sem serem criados. Não informa se as tarefas de implementação estão completas. isComplete é mantido como um alias de compatibilidade com o mesmo valor.

Os artefatos são listados em ordem de dependência — uma dependência nunca aparece depois de algo que a requer — e artefatos que ficam prontos ao mesmo tempo (no fluxo spec-driven, specs e design precisam apenas de proposal) mantêm a ordem declarada pelo schema, em vez de ordem alfabética. Assim, a primeira entrada ready é o artefato a ser escrito em seguida.

`openspec instructions`

Obtém instruções enriquecidas para criar um artefato ou aplicar tarefas. Usado por agentes de IA para entender o que criar a seguir.

openspec instructions [artefato] [opções]

Argumentos:

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

Opções:

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

Casos especiais: Use apply para obter instruções de implementação de tarefas. Use archive para obter os inputs de arquivamento atuais, somente leitura (context e operationGuidance) para uma mudança válida; não arquiva nem modifica nada.

Exemplos:

bash

# Obter instruções para o próximo artefato
openspec instructions --change add-dark-mode

# Obter instruções para um artefato específico
openspec instructions design --change add-dark-mode

# Obter instruções de apply/implementação
openspec instructions apply --change add-dark-mode

# Obter os inputs da operação de arquivamento atuais sem arquivar
openspec instructions archive --change add-dark-mode --json

# JSON para consumo por agentes
openspec instructions design --change add-dark-mode --json

A saída inclui:

Conteúdo do template para o artefato
Contexto do projeto a partir da configuração
Conteúdo dos artefatos de dependência
Regras por artefato da configuração
Contexto atual do projeto e orientação de operação correspondente para apply/archive

Os inputs da operação são lidos do repositório resolvido ou do store selecionado a cada invocação. O contexto do projeto é uma entrada obrigatória em nível de prompt: agentes o leem e aplicam fatos, convenções e restrições relevantes do projeto. A orientação de operação é um conselho aditivo opcional: os agentes consideram cada entrada e seguem apenas aquelas que são aplicáveis e compatíveis com o workflow embutido. Ambos os campos permanecem separados das escolhas explícitas do usuário, do estado controlado pela CLI, das instruções embutidas e das regras de artefatos. Contextos conflitantes são reportados; orientações conflitantes ou inaplicáveis não são seguidas e o motivo é explicado. Esses são contratos comportamentais para agentes gerados, não verificações impostas pela CLI. instructions archive retorna apenas a mudança selecionada, inputs opcionais e metadados da raiz; não inclui o workflow de arquivamento estático.

Para um artefato ignorado via skip_specs: true, a saída é apenas um aviso (JSON adiciona os campos skipped/warning) — o artefato não deve ser criado.

`openspec templates`

Mostra os caminhos resolvidos de templates para todos os artefatos em um schema.

openspec templates [opções]

Opções:

Opção	Descrição
`--schema <nome>`	Schema a ser inspecionado (padrão: `spec-driven`)
`--json`	Saída em JSON

Exemplos:

bash

# Mostrar caminhos de templates para o schema padrão
openspec templates

# Mostrar templates para um schema personalizado
openspec templates --schema my-workflow

# JSON para uso programático
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`

Lista os schemas de workflow disponíveis com suas descrições e fluxos de artefatos.

openspec schemas [opções]

Opções:

Opção	Descrição
`--json`	Saída em JSON
`--store <id>`	Usa um store registrado como raiz do OpenSpec

Exemplo:

bash

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 workflow personalizados.

`openspec schema init`

Cria 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 artefatos separados por vírgula (padrão: `proposal,specs,design,tasks`)
`--default`	Definir como schema padrão do projeto
`--no-default`	Não solicitar para definir como padrão
`--force`	Substituir schema existente
`--json`	Saída em JSON

Exemplos:

bash

# Criação interativa de schema
openspec schema init research-first

# Não interativo com artefatos específicos
openspec schema init rapid \
  --description "Rapid iteration workflow" \
  --artifacts "proposal,tasks" \
  --default

O que ele cria:

openspec/schemas/<name>/
├── schema.yaml           # Definição do schema
└── templates/
    ├── proposal.md       # Template para cada artefato
    ├── specs.md
    ├── design.md
    └── tasks.md

`openspec schema fork`

Copia um schema existente para o seu projeto para personalização.

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

Argumentos:

Argumento	Obrigatório	Descrição
`source`	Sim	Schema a ser copiado
`name`	Não	Novo nome do schema (padrão: `<source>-custom`)

Opções:

Opção	Descrição
`--force`	Substituir destino existente
`--json`	Saída em JSON

Exemplo:

bash

# Criar fork do schema spec-driven embutido
openspec schema fork spec-driven my-workflow

`openspec schema validate`

Valida a estrutura e os templates de um schema.

openspec schema validate [name] [options]

Argumentos:

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

Opções:

Opção	Descrição
`--verbose`	Mostrar etapas detalhadas de validação
`--json`	Saída em JSON

Exemplo:

bash

# Validar um schema específico
openspec schema validate my-workflow

# Validar todos os schemas
openspec schema validate

`openspec schema which`

Mostra de onde um schema é resolvido (útil para depurar 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 com suas origens
`--json`	Saída em JSON

Exemplo:

bash

# Verificar de onde um schema vem
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 de schemas:

Projeto: openspec/schemas/<name>/
Usuário: ~/.local/share/openspec/schemas/<name>/
Pacote: Schemas embutidos

Comandos de Configuração

`openspec config`

Visualizar e modificar a configuração global do OpenSpec.

openspec config <subcommand> [options]

Subcomandos:

Subcomando	Descrição
`path`	Mostrar localização do arquivo de configuração
`list`	Mostrar 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 padrões
`edit`	Abrir no `$EDITOR`
`profile [preset]`	Configurar perfil de workflow interativamente ou via preset

Exemplos:

bash

# Mostrar caminho do arquivo de configuração
openspec config path

# Listar todas as configurações
openspec config list

# Obter um valor específico
openspec config get telemetry.enabled

# Definir um valor (desativar telemetria de uso anônimo)
openspec config set telemetry.enabled false

# Definir um valor de string explicitamente
openspec config set user.name "My Name" --string

# Remover uma configuração personalizada
openspec config unset user.name

# Definir um armazenamento padrão em nível de máquina (raiz de fallback quando não há --store,
# raiz local ou armazenamento do projeto: o ponteiro é resolvido)
openspec config set defaultStore team-plans

# Restaurar toda a configuração
openspec config reset --all --yes

# Editar configuração no seu editor
openspec config edit

# Configurar perfil com assistente baseado em ações
openspec config profile

# Preset rápido: alternar workflows para core (mantém o modo de entrega)
openspec config profile core

Opt-out de telemetria: telemetry.enabled é ativado por padrão quando não definido (modelo de opt-out). Defina-o como false para desativar estatísticas de uso anônimas e a verificação de versão do openspec update. Variáveis de ambiente têm precedência sobre a configuração: OPENSPEC_TELEMETRY=0, DO_NOT_TRACK=1, e um valor verdadeiro de CI (ex.: true/1/yes) sempre desativam a telemetria, independentemente do valor de configuração.

openspec config profile começa com um resumo do estado atual e então permite que você escolha:

Alterar entrega + workflows
Alterar apenas entrega
Alterar apenas workflows
Manter configurações atuais (sair)

Se você manter 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 do projeto atual estiverem dessincronizados com seu perfil/entrega global, o OpenSpec exibirá um aviso e sugerirá openspec update. Pressionar Ctrl+C também cancela o fluxo de forma limpa (sem stack trace) e sai com código 130. Na lista de verificação de workflows, [x] significa que o workflow 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 solicitado dentro de um projeto).

Exemplos interativos:

bash

# Atualização apenas de entrega
openspec config profile
# escolha: Change delivery only
# escolha entrega: Skills only

# Atualização apenas de workflows
openspec config profile
# escolha: Change workflows only
# alterne workflows na lista de verificação e confirme

Comandos de Utilidade

`openspec feedback`

Enviar feedback sobre o OpenSpec. Cria uma issue no GitHub.

openspec feedback <message> [options]

Argumentos:

Argumento	Obrigatório	Descrição
`message`	Sim	Resumo do feedback; texto longo é encurtado no título da issue e preservado no corpo

Opções:

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

Requisitos: O GitHub CLI (gh) deve estar instalado e autenticado.

Exemplo:

bash

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`

Gerenciar complementações de shell para a CLI do OpenSpec.

openspec completion <subcommand> [shell]

Subcomandos:

Subcomando	Descrição
`generate [shell]`	Exibir script de complementação no stdout
`install [shell]`	Instalar complementação para o seu shell
`uninstall [shell]`	Remover complementações instaladas

Shells suportados: bash, zsh, fish, powershell

Exemplos:

bash

# Instalar complementações (detecta shell automaticamente)
openspec completion install

# Instalar para shell específico
openspec completion install zsh

# Gerar script para instalação manual (bash)
openspec completion generate bash > ~/.bash_completion.d/openspec

# Desinstalar
openspec completion uninstall

Windows (PowerShell): Instale complementações para o host PowerShell atual:

powershell

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

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

Para desinstalar do host atual, execute:

powershell

$env:PROFILE = $PROFILE
openspec completion uninstall powershell

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

As complementações são opt-in. A CLI as menciona uma vez, no stderr, na primeira vez que você executa um comando em um terminal interativo, e nunca novamente — ela também permanece silenciosa se você já tiver complementações instaladas. Defina OPENSPEC_NO_COMPLETIONS=1 para suprimir completamente essa dica.

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 telemetria e a verificação de versão do `openspec update` (sobrescreve `telemetry.enabled` na configuração global)
`DO_NOT_TRACK`	Defina como `1` para desativar telemetria e a verificação de versão do `openspec update` (sinal padrão de DNT; sobrescreve configuração)
`OPENSPEC_CONCURRENCY`	Concorrência padrão para validação em lote (padrão: 6)
`EDITOR` ou `VISUAL`	Editor para `openspec config edit`
`NO_COLOR`	Desativar saída colorida quando definida
`OPENSPEC_NO_ANIMATION`	Desativar a animação de boas-vindas do `openspec init` quando definida
`OPENSPEC_NO_COMPLETIONS`	Defina como `1` para suprimir a dica única sobre complementações de shell
`OPENSPEC_NO_UPDATE_CHECK`	Desativar a verificação do `openspec update` por uma versão mais recente da CLI publicada quando definida (qualquer valor, incluindo vazio). Também é ignorada quando `CI` está definida (a menos que seja `false`/`0`/`no`/`off`) ou `NODE_ENV=test`
`npm_config_registry`	Registro que a verificação de versão do `openspec update` consulta. Deve ser uma URL `http(s)` ou ela usa `https://registry.npmjs.org` como fallback. Nenhum arquivo `.npmrc` é lido

Documentação Relacionada

Commands - Comandos slash de IA (/opsx:propose, /opsx:apply, etc.)
Workflows - Padrões comuns e quando usar cada comando
Customization - Criar schemas e templates personalizados
Getting Started - Guia de configuração inicial

Referência da CLI ​

Resumo ​

Comandos para Humanos vs Agentes ​

Comandos Exclusivos para Humanos ​

Comandos Compatíveis com Agentes ​

Opções Globais ​

Comandos de Configuração ​

openspec init ​

openspec update ​

Stores (repositórios OpenSpec independentes) ​

openspec store setup ​

openspec store register ​

openspec store unregister ​

openspec store remove ​

openspec store list ​

openspec store doctor ​

Referenciando stores a partir de um projeto ​

Gravando de onde uma store foi clonada ​

Declarando uma store padrão ​

Doctor (saúde do relacionamento) ​

Contexto de trabalho (o conjunto montado) ​

Conjuntos de trabalho pessoais ​

Comandos de Navegação ​

openspec list ​

openspec view ​

openspec show ​

Comandos de Validação ​

openspec validate ​

Comandos de Ciclo de Vida ​

openspec archive ​

Comandos de Workflow ​

openspec new change ​

openspec status ​

openspec instructions ​

openspec templates ​

openspec schemas ​

Comandos de Schema ​

openspec schema init ​

openspec schema fork ​

openspec schema validate ​

openspec schema which ​

Comandos de Configuração ​

openspec config ​

Comandos de Utilidade ​

openspec feedback ​

openspec completion ​

Códigos de Saída ​

Variáveis de Ambiente ​

Documentação Relacionada ​

Referência da CLI

Resumo

Comandos para Humanos vs Agentes

Comandos Exclusivos para Humanos

Comandos Compatíveis com Agentes

Opções Globais

Comandos de Configuração

`openspec init`

`openspec update`

Stores (repositórios OpenSpec independentes)

`openspec store setup`

`openspec store register`

`openspec store unregister`

`openspec store remove`

`openspec store list`

`openspec store doctor`

Referenciando stores a partir de um projeto

Gravando de onde uma store foi clonada

Declarando uma store padrão

Doctor (saúde do relacionamento)

Contexto de trabalho (o conjunto montado)

Conjuntos de trabalho pessoais

Comandos de Navegação

`openspec list`

`openspec view`

`openspec show`

Comandos de Validação

`openspec validate`

Comandos de Ciclo de Vida

`openspec archive`

Comandos de Workflow

`openspec new change`

`openspec status`

`openspec instructions`

`openspec templates`

`openspec schemas`

Comandos de Schema

`openspec schema init`

`openspec schema fork`

`openspec schema validate`

`openspec schema which`

Comandos de Configuração

`openspec config`

Comandos de Utilidade

`openspec feedback`

`openspec completion`

Códigos de Saída

Variáveis de Ambiente

Documentação Relacionada