Referência do Specsfy CLI: comandos, opções e exemplos

Esta referência descreve a interface pública do specsfy 0.8.1. O caminho informado por --project deve apontar para a raiz do projeto consumidor. Sem essa opção, o CLI usa o diretório atual. Os comandos que consultam catálogo ou versões privadas usam GH_TOKEN, GITHUB_TOKEN ou a sessão de gh auth token.

Para aprender o percurso pela interface visual, consulte o guia do CLI e da TUI. Para preparar o primeiro projeto, comece pela instalação.

specsfy

Abre a TUI no diretório atual. Não recebe argumentos. Antes do dashboard, pode consultar uma versão estável mais recente e pedir autorização para atualizar o pacote global. A recusa ou uma falha de rede preserva a versão instalada.

Exemplos:

1
specsfy
2
cd aplicativo && specsfy
3
GH_TOKEN="$TOKEN_SPECSFY" specsfy
4
GITHUB_TOKEN="$TOKEN_SPECSFY" specsfy
5
SPECSFY_SPECIALISTS_CATALOG=/tmp/catalog.json specsfy

specsfy install

Instala as skills base, regras, templates, exemplo e blocos gerenciados no projeto. --detected acrescenta os especialistas encontrados pela stack. --specialist <nome> pode ser repetido. --force permite substituir conteúdo gerenciado que recebeu alteração local. --json emite a lista de caminhos alterados como JSON. O comando recusa a raiz do monorepo oficial.

Exemplos:

1
specsfy install --project .
2
specsfy install --project ./aplicativo --json
3
specsfy install --project . --detected
4
specsfy install --project . --specialist specsfy-specialist-laravel
5
specsfy install --project . --detected --force --json

specsfy doctor

Verifica Node.js, Git, npm, acesso de leitura e escrita ao projeto e a disponibilidade do npx. A resolução usa npx encontrado no PATH ou o override técnico SPECSFY_NPX_COMMAND, a instalação materializa skills por npx skills add. --json retorna cada item, seu estado e o comando encontrado. Qualquer requisito ausente produz exit code 1.

Exemplos:

1
specsfy doctor
2
specsfy doctor --project .
3
specsfy doctor --project ./api
4
specsfy doctor --json
5
specsfy doctor --project ./api --json

specsfy update

Atualiza todas as skills Specsfy registradas no projeto, incluindo skills base, auxiliares, setup, documentador e especialistas. Skills externas e templates customizados permanecem intocados. --force substitui conteúdo gerenciado alterado e --json informa os caminhos modificados. O comando executa o diagnóstico de instalação antes do download.

Exemplos:

1
specsfy update
2
specsfy update --project .
3
specsfy update --project ./api
4
specsfy update --force
5
specsfy update --project ./api --force --json

specsfy upgrade

Consulta novamente a versão publicada no npm e atualiza o próprio CLI pelo pacote @promovaweb/specsfy@latest. O npm só é executado quando a versão encontrada é superior à versão atual, o que impede downgrade e ignora um adiamento anterior. --json informa se houve atualização e as versões envolvidas. O projeto não é alterado.

Exemplos:

1
specsfy upgrade
2
specsfy upgrade --json
3
GH_TOKEN="$TOKEN_SPECSFY" specsfy upgrade
4
GITHUB_TOKEN="$TOKEN_SPECSFY" specsfy upgrade --json
5
PATH="$HOME/.npm-global/bin:$PATH" specsfy upgrade

specsfy skills list

Lista o catálogo do framework e dos especialistas. --json entrega objetos estruturados para automação. A leitura consulta o catálogo remoto, exceto quando SPECSFY_SPECIALISTS_CATALOG aponta para uma fonte local.

Exemplos:

1
specsfy skills list
2
specsfy skills list --json
3
specsfy skills list --json > /tmp/specsfy-skills.json
4
GH_TOKEN="$TOKEN_SPECSFY" specsfy skills list
5
SPECSFY_SPECIALISTS_CATALOG=./catalog.json specsfy skills list --json

specsfy skills detect

Compara os arquivos do projeto com as regras do catálogo e retorna as skills recomendadas. --project <caminho> seleciona a raiz e --json fornece saída estruturada. O comando apenas consulta, sem instalar arquivos.

Exemplos:

1
specsfy skills detect
2
specsfy skills detect --project .
3
specsfy skills detect --project ./api --json
4
GH_TOKEN="$TOKEN_SPECSFY" specsfy skills detect --project .
5
SPECSFY_SPECIALISTS_CATALOG=./catalog.json specsfy skills detect --json

specsfy skills install

Depois de revisar a recomendação e autorizar a instalação, este comando usa npx skills add com o repositório oficial e somente os nomes necessários. Ele materializa a skill no projeto atual, não instale o catálogo inteiro por padrão.

Exemplos:

1
specsfy skills install specsfy-specialist-laravel
2
specsfy skills install specsfy-specialist-postgres --project ./api
3
specsfy skills install specsfy-specialist-laravel specsfy-specialist-postgres
4
specsfy skills install specsfy-specialist-react-ui-components --project .
5
specsfy skills install specsfy-specialist-interface-experience --project .

specsfy skills remove

Remove somente as skills nomeadas e preserva skills externas presentes no mesmo lock. Os nomes são obrigatórios. Conteúdo local divergente impede a remoção, a menos que --force seja informado. A saída lista os caminhos alterados.

Exemplos:

1
specsfy skills remove specsfy-specialist-laravel
2
specsfy skills remove specsfy-specialist-postgres --project ./api
3
specsfy skills remove specsfy-specialist-laravel specsfy-specialist-postgres
4
specsfy skills remove specsfy-specialist-react-ui-components --project .
5
specsfy skills remove specsfy-specialist-laravel --project . --force

specsfy skills update

Alias compatível de specsfy update. Atualiza todas as skills Specsfy já instaladas. --project <caminho> seleciona o projeto. --force permite substituir conteúdo gerenciado alterado e --json retorna os caminhos. Skills externas e arquivos de .specsfy/templates/custom/ permanecem intocados.

Exemplos:

1
specsfy skills update
2
specsfy skills update --project .
3
specsfy skills update --project ./api
4
specsfy skills update --force
5
specsfy skills update --project ./api --force

specsfy transition

Move uma spec para draft, defined, planned, in-progress, review ou completed e atualiza o campo Status no mesmo ato. O identificador e o estado são obrigatórios. --json inclui o caminho resultante e o handoff opcional do ClickUpfy. O comando recusa transições não permitidas e sincroniza os milestones após a escrita.

Exemplos:

1
specsfy transition 0001-recuperar-senha defined
2
specsfy transition 0001-recuperar-senha planned --project .
3
specsfy transition 0001-recuperar-senha in-progress --json
4
specsfy transition 0001-recuperar-senha review --project ./api
5
specsfy transition 0001-recuperar-senha completed --project . --json

specsfy migrate

Move specs do layout anterior para as pastas do ciclo de vida e alinha o campo Status. --project <caminho> seleciona a raiz. --json retorna a coleção migrated. Quando não há fonte legada, a execução não altera arquivos.

Exemplos:

1
specsfy migrate
2
specsfy migrate --project .
3
specsfy migrate --project ./api
4
specsfy migrate --json
5
specsfy migrate --project ./api --json

specsfy effort

Registra a pontuação inteira de 1 a 10 e sua justificativa na spec. O identificador, a pontuação e --reason <texto> são obrigatórios. --json inclui o resultado e o handoff opcional do ClickUpfy. Pontuação fora do intervalo ou spec ambígua é recusada.

Exemplos:

1
specsfy effort 0001-recuperar-senha 3 --reason "Alteração local."
2
specsfy effort 0001-recuperar-senha 5 --reason "Inclui testes de integração."
3
specsfy effort 0001-recuperar-senha 7 --reason "Inclui migração." --project .
4
specsfy effort 0001-recuperar-senha 8 --reason "Depende de API externa." --json
5
specsfy effort 0001-recuperar-senha 10 \
6
  --reason "Entrega distribuída." --project ./api --json

specsfy progress

Lê specs e calcula estados, gates, Effort, tarefas, checklists e porcentagens. --json retorna summary e specs. --watch permanece ativo e só emite um novo snapshot após mudança das fontes. --interval <segundos> configura a espera do watch e deve ser maior que zero. O comando não altera o projeto.

Exemplos:

1
specsfy progress
2
specsfy progress --project .
3
specsfy progress --project ./api --json
4
specsfy progress --watch
5
specsfy progress --project . --watch --interval 0.5 --json

specsfy milestones sync

Projeta os vínculos declarados nas specs e no backlog para specs.md e specs/milestones/MNN.md. Somente blocos gerados são substituídos. --json retorna o caminho do índice e os totais de cada milestone. Referências inválidas ou metadados ambíguos interrompem a escrita.

Exemplos:

1
specsfy milestones sync
2
specsfy milestones sync --project .
3
specsfy milestones sync --project ./api
4
specsfy milestones sync --json
5
specsfy milestones sync --project ./api --json

specsfy test

Detecta um projeto Laravel com Pest, executa php artisan test, transmite a saída e devolve o mesmo exit code. --project <caminho> seleciona a raiz. O comando não aceita uma string arbitrária de shell e recusa projetos sem runner compatível. Antes de iniciar o processo PHP, exige .env.testing com APP_ENV=testing e um DB_DATABASE ou DB_URL explícito, separado do .env. Também recusa RefreshDatabase e DatabaseMigrations. A TUI aplica o mesmo gate, quando a configuração estiver pendente, nenhum teste é iniciado.

Exemplos:

1
specsfy test
2
specsfy test --project .
3
specsfy test --project ./api
4
NO_COLOR=1 specsfy test --project .
5
specsfy test --project "./aplicativo Laravel"

specsfy tui

Abre explicitamente o dashboard para o projeto selecionado. --project recebe um caminho e usa o diretório atual por padrão. A TUI pode escrever configuração, instalar skills e executar testes somente após uma ação da pessoa. Ctrl+Q encerra a interface.

Exemplos:

1
specsfy tui
2
specsfy tui --project .
3
specsfy tui --project ./api
4
GH_TOKEN="$TOKEN_SPECSFY" specsfy tui --project .
5
SPECSFY_SPECIALISTS_CATALOG=./catalog.json specsfy tui --project .

specsfy config show

Lê a configuração efetiva de .specsfy/config.json. --project seleciona a raiz e --json fornece saída estruturada. A ausência do arquivo usa os valores padrão e não cria configuração.

Exemplos:

1
specsfy config show
2
specsfy config show --project .
3
specsfy config show --project ./api
4
specsfy config show --json
5
specsfy config show --project ./api --json

specsfy config set

Grava o intervalo de atualização da TUI em .specsfy/config.json. --watch-interval <segundos> é obrigatório e aceita número positivo. --project seleciona a raiz e --json retorna a configuração resultante. Chaves desconhecidas existentes são preservadas.

Exemplos:

1
specsfy config set --watch-interval 0.5
2
specsfy config set --project . --watch-interval 0.75
3
specsfy config set --project ./api --watch-interval 1
4
specsfy config set --watch-interval 2 --json
5
specsfy config set --project ./api --watch-interval 5 --json

Justificativa de tamanho

A referência mantém comandos, parâmetros, efeitos, recusas e exemplos no mesmo arquivo para que a cobertura automatizada compare a gramática executável com uma única fonte. Separar cada comando impediria essa conferência direta e espalharia opções compartilhadas por várias páginas.

Confirmação e diagnóstico

Depois de qualquer escrita, confirme o resultado com uma leitura compatível: skills list, progress, milestones sync --json ou config show --json. Falhas do CLI são impressas em stderr com o prefixo erro: e retornam exit code diferente de zero. --help mostra a gramática instalada e --version confirma qual release está sendo executada.