Instalação

Instale a CLI openspec na sua máquina, atualize-a e desinstale-a.

Instalar

No macOS ou Linux, no seu terminal:

curl -fsSL https://openspec.dev/cli/install.sh | sh

No Windows, no PowerShell:

irm https://openspec.dev/cli/install.ps1 | iex

Se o instalador imprimir uma linha export PATH=..., execute-a. Em seguida, verifique se funcionou.

Instalar com seu assistente de IA

Cole isto no seu chat de IA:

Fetch https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/install.md and follow it.

Ou, no seu terminal, envie-o via pipe para um agente de CLI (Claude Code mostrado):

curl -fsSL https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/install.md | claude

Isso busca o install.md na raiz do repositório, um prompt escrito para qualquer agente que consiga executar comandos de shell (algumas integrações de IDE não conseguem). Espere que seu assistente:

1. Pule a instalação se a CLI já estiver na sua máquina e ofereça atualizá-la da forma como foi instalada. Se foi via npm ou Homebrew, mencione uma vez que openspec install muda para a instalação autônoma, sem insistir. Caso contrário, mostre o comando de instalação acima e aguarde sua confirmação antes de executá-lo.
2. Use npm em vez disso apenas se você pedir ou se o instalador falhar, e pare se seu Node for mais antigo que 22.12.0.
3. Verifique se openspec está no seu PATH.
4. Identifique a pasta que ele acha que você quer dizer, sugira a ferramenta de IA com a qual você já está conversando e pergunte quais outras você usa; depois, execute openspec init nela (a etapa de configuração do projeto).
5. Informe o que o init criou e a grafia exata para invocar o OpenSpec na sua ferramenta.

Ele para antes de qualquer ação privilegiada e nunca edita seus arquivos de inicialização do shell. O comando de instalação acima e os gerenciadores de pacotes abaixo são a fonte da verdade, e o prompt os executa para você.

Este método de instalação é novo e pode ter resultados variados dependendo do modelo usado. Use apenas se você estiver à vontade para corrigir erros da IA. Caso contrário, recomendamos seguir o método padrão abaixo.

Gerenciadores de pacotes

Eles instalam o OpenSpec como um pacote Node.js, então precisam do Node.js 22.12.0 ou mais recente (Homebrew e Nix trazem o próprio). No seu terminal:

node --version

Se isso imprimir v22.12.0 ou superior, instale com npm:

npm install -g @fission-ai/openspec@latest

Caso contrário, instale um Node mais novo a partir de nodejs.org ou por meio do seu gerenciador de versões (nvm, fnm, asdf, volta), ou use a instalação autônoma em vez disso.

Homebrew

O Homebrew instala o OpenSpec e sua dependência Node.js no macOS ou Linux. No seu terminal:

brew install openspec

A fórmula é publicada no homebrew-core, então você não precisa adicionar um tap.

Yarn

yarn global add é apenas do Yarn Classic (1.x). O Yarn moderno removeu instalações globais, então use npm, pnpm ou bun. Uma CLI global não precisa compartilhar o gerenciador de pacotes do seu projeto.

Bun

O Bun instala o OpenSpec, mas não o executa, então você ainda precisa do Node na sua máquina (veja Gerenciadores de pacotes). Sem ele, todo comando falha com env: node: No such file or directory. O Bun trata toda CLI Node dessa forma.

Deno

O Deno instala a CLI a partir do npm e precisa de flags de permissão explícitas. No seu terminal:

deno install --global \
  --allow-read --allow-write --allow-env --allow-sys=cpus,homedir --allow-net=edge.openspec.dev \
  npm:@fission-ai/openspec@latest

Alguns comandos iniciam outro programa: openspec config edit abre seu editor. O Deno interrompe esses comandos com um prompt de permissão a cada execução. Para impedir que ele pergunte, adicione um --allow-run=<program> com escopo ao comando de instalação.

NOTE

Se o Deno não conseguir resolver @latest, fixe um intervalo de versão em vez disso: npm:@fission-ai/openspec@^1.7.0.

Nix

O repositório do OpenSpec inclui um flake Nix. Instale-o no seu perfil. No seu terminal:

nix profile install github:Fission-AI/OpenSpec

Ou execute um comando avulso primeiro, sem instalar:

nix run github:Fission-AI/OpenSpec -- --version

Isso não deixa nada no seu PATH, então não há instalação a verificar depois.

Para colocar o OpenSpec em um dev shell de projeto, adicione o flake como uma entrada e use seu pacote padrão; o flake.nix lista as saídas.

O pacote Nix inclui os scripts de completion para Bash, Fish e Zsh nos locais padrão (share/bash-completion/completions, share/fish/vendor_completions.d, share/zsh/site-functions), então eles são carregados com o pacote e não há necessidade de executar openspec completion install.

Verifique se funcionou

Independentemente do método usado, no seu terminal:

openspec --version

Se isso imprimir um número de versão, a CLI está no seu PATH. Ela é instalada uma vez por máquina.

Em seguida, configure seu projeto. Se seu assistente já executou o init, essa página mostra o que ele gravou e como ajustá-lo.

Opções de instalação

Para escolher uma versão ou uma pasta, defina uma variável antes de sh:

curl -fsSL https://openspec.dev/cli/install.sh | OPENSPEC_VERSION=v1.15.0 sh

• OPENSPEC_VERSION: a versão a instalar, como v1.15.0. O padrão é a versão mais recente.
• OPENSPEC_INSTALL_DIR: a pasta de instalação. O padrão é ~/.local/bin (Windows: %LOCALAPPDATA%\Programs\openspec).

No Windows, defina a variável primeiro:

$env:OPENSPEC_VERSION = 'v1.15.0'
irm https://openspec.dev/cli/install.ps1 | iex

No Alpine Linux, execute apk add libstdc++ libgcc antes de instalar.

Baixar manualmente

Cada versão tem um arquivo por computador:

Computador	Arquivo
Mac, Apple silicon	openspec-darwin-arm64.tar.gz
Mac, Intel	openspec-darwin-x64.tar.gz
Linux, arm64	openspec-linux-arm64.tar.gz
Linux, x64	openspec-linux-x64.tar.gz
Alpine, arm64	openspec-linux-arm64-musl.tar.gz
Alpine, x64	openspec-linux-x64-musl.tar.gz
Windows, arm64	openspec-windows-arm64.zip
Windows, x64	openspec-windows-x64.zip

1. Baixe seu arquivo na versão mais recente. Os arquivos são anexados alguns minutos após a publicação de uma versão. Se o seu ainda não estiver listado, aguarde e recarregue, ou pegue-o da versão anterior.
2. Descompacte-o. No seu terminal: tar -xzf openspec-darwin-arm64.tar.gz. No Windows, clique com o botão direito no .zip e escolha Extrair Tudo.
3. No macOS, execute xattr -d com.apple.quarantine openspec na pasta em que você descompactou. O macOS bloqueia arquivos baixados em um navegador até que você faça isso.
4. Mova o openspec para uma pasta no seu PATH, como ~/.local/bin. No Windows, mova openspec.exe para uma pasta no PATH do seu usuário, como %LOCALAPPDATA%\Programs\openspec.

Verificar um download

Para verificar se um arquivo foi criado pelo workflow de lançamento do OpenSpec, execute isto com a GitHub CLI:

gh attestation verify openspec-darwin-arm64.tar.gz --repo Fission-AI/OpenSpec

Ele falha se o workflow não tiver criado o arquivo. O comando de instalação já verifica cada download em relação ao SHA256SUMS da versão, então esta etapa é opcional.

Mudar do npm para a instalação autônoma

A mudança é opcional; o npm continua funcionando. Suas configurações e seus projetos são mantidos; apenas o programa muda.

1. Instale a cópia autônoma. No seu terminal:

openspec install

Isso instala o openspec autônomo e imprime o comando que remove sua cópia do npm ou do Homebrew.

2. Remova a cópia antiga. Ela geralmente vem primeiro no seu PATH, então, até ser removida, continua sendo executada. Execute o comando impresso na etapa 1, por exemplo:

npm uninstall -g @fission-ai/openspec

3. Verifique qual cópia é executada. Abra um novo terminal:

openspec version

Isso deve imprimir OpenSpec <version> (standalone). Se, em vez disso, ele indicar um gerenciador de pacotes, outra cópia ainda está no seu PATH: which -a openspec (Windows: where.exe openspec) lista todas as cópias, então remova as outras.

Nenhum projeto precisa ser reinicializado. Para voltar atrás, exclua o arquivo e execute a instalação npm novamente.

Atualização

No seu terminal, em cada projeto em que você executou o init:

openspec update

Quando uma CLI mais nova for lançada, openspec update avisa e pode instalá-la para você; essa atualização ocorre uma vez por máquina. Cada execução atualiza as skills e os comandos gerados do projeto, que nunca se atualizam por conta própria. Um projeto atualizado imprime ✓ All 2 tool(s) up to date (v1.7.0).

WARNING

Com a instalação autônoma, execute openspec install para substituir sua cópia no mesmo local; openspec update avisa quando uma versão mais nova estiver disponível. No Homebrew, execute brew upgrade openspec. No Deno, execute novamente a instalação via Deno com -f; sem isso, ele não substituirá o comando instalado. No Nix, use nix profile upgrade openspec.

NOTE

Uma instalação global do npm pertence a uma instalação do Node. Se você trocar a versão do Node com o nvm, o comando openspec não vem junto, então instale-o novamente na nova versão.

Desinstalação

Para desinstalar o OpenSpec, siga as etapas abaixo; nenhuma delas altera seu código-fonte. Você também pode indicar esta seção ao seu agente e deixar que ele faça a remoção.

1. Remova os completions do shell, se você os configurou, enquanto a CLI ainda pode fazer isso. No seu terminal:

openspec completion uninstall

2. Remova a CLI. Para a instalação autônoma, exclua ~/.local/bin/openspec (Windows: %LOCALAPPDATA%\Programs\openspec, e essa pasta do PATH do seu usuário). Para npm, no seu terminal:

npm uninstall -g @fission-ai/openspec

No Homebrew: brew uninstall openspec. No Deno: deno uninstall --global openspec. No Nix: nix profile remove openspec. Seu shell não deve mais encontrar openspec.

3. Exclua o que restar ou mantenha.

• Arquivos de agente gerados: skills openspec-* e comandos opsx em diretórios como .claude/ ou .agents/, por projeto. Ferramentas compatíveis lista os caminhos de cada ferramenta; o MiniMax Code mantém as skills em ~/.minimax/skills.
• Resíduos de versões mais antigas: blocos de marcador em CLAUDE.md ou AGENTS.md (exclua o bloco, mantenha o arquivo) e prompts opsx-*.md em ~/.codex/prompts.
• A pasta openspec/: pense duas vezes antes. specs/ e changes/archive/ são o registro do seu sistema, Markdown simples que pode ser lido sem problemas sem o OpenSpec.
• Estado por máquina: configurações e o id de telemetria em ~/.config/openspec/; substituições de schema, registros de store e os schemas integrados da instalação autônoma (binary-schemas/) em ~/.local/share/openspec/ (Windows: %APPDATA%\openspec, %LOCALAPPDATA%\openspec). Os registros são ponteiros; os repositórios de store para os quais eles apontam não são alterados.