SpecNote CLI

Interface de linha de comando para gerenciar o backend do SpecNote com suporte a múltiplos perfis de autenticação (Multi-Auth).

🤖 Para agentes de IA

Esta CLI é IA-first — você consegue se virar sozinho sem ler a documentação web. Comece por:

sn explain               # índice de tópicos
sn explain quick-start   # 5 comandos para começar
sn explain auth          # modelo dual-token (master + organization)
sn explain domain        # Project → Scope → Requirement → Task
sn explain snapshot      # backup/restore via YAML
sn explain errors        # erros HTTP comuns
sn explain cli           # convenções da própria CLI

sn <comando> --help      # cada comando tem exemplos no final do help

Guia direto pra agentes em AGENTS.md. Após npm install -g, todos os arquivos em ./docs/ ficam disponíveis em node_modules/@specnote/cli/docs/ para leitura sem rede.

📚 Documentação

• Autenticação e Perfis - Sistema completo de autenticação multi-perfis
• Requisições HTTP - Interface curl-like para API
• Organizações - Gerenciamento de empresas/clientes
• Projetos - Gerenciamento de projetos
• Escopos - Escopos de trabalho e entregas
• Aplicações - Aplicações e sistemas desenvolvidos
• Tarefas - Gerenciamento detalhado de tarefas
• Requisitos - Requisitos funcionais e não-funcionais
• Guia Técnico - Arquitetura e desenvolvimento

🚨 Mudanças Recentes

v1.0.4 — Snapshot de projeto + bin alias sn

• sn proj export/validate/import para backup/restore de Project + Scopes + Requirements via YAML versionado.
• sn agora é alias do specnote (mesmo binário, comando curto).

v1.0.5 — Fix auth organization-token

• Corrigido bug que falhava ao ler o token gerado (envelope da resposta).

v1.0.6 — IA-first

• Novo sn explain <topic>: tópicos focados em agentes (quick-start, auth, domain, snapshot, errors, cli).
• addHelpText("after") em comandos críticos com exemplos copy-paste.
• AGENTS.md distribuído junto do pacote.
• docs/ empacotado para leitura offline em node_modules/@specnote/cli/docs/.

v1.0.7 — Fix switch-org / login consistência

• Resolve trap onde login → switch-org → ... → login deixava o profile em estado inconsistente (token master mas tokenType: organization no metadado), causando 403 em todas as rotas multi-tenant e switch-org se recusando a regenerar.
• login agora reseta campos de org. switch-org valida o JWT real antes do early-return. organization-token persiste por default (com --no-save opt-out). auth me denuncia mismatch profile/JWT.

v1.0.8 — Fix specs list

• Argumentos posicionais corrigidos para o SDK regenerado (estavam fora de ordem).
• Combina com fix correspondente no backend que tolera querystring ?type= vazio.

v1.0.9+ — Não-interativo automático em pipe/CI

• Detecção de TTY: em pipe/script/IA/CI, comandos com required ausentes falham rápido com lista exata de flags faltando, em vez de pendurar em prompt.
• Em terminal real, prompt continua funcionando como sempre.
• Aplicado em auth login, specs/scope/apps/tasks create. Sem flag nova — TTY automático.

Histórico anterior (v1.0.2+)

1. Comandos modulares — divididos em subcomandos especializados.
2. --data para entrada JSON, --json para formatação de saída.
3. SDK gerado automaticamente do OpenAPI do backend.
4. Publicação no NPM.
5. Comando request estilo curl.
6. Filtro por organização automático.
7. IDs truncados (8 dígitos) em tabelas.

Instalação

Global (Recomendado)

npm install -g @specnote/cli
# ou
sudo npm install -g @specnote/cli

Local (Para desenvolvimento)

cd packages/cli
pnpm install
pnpm build

🚀 Quick Start (Início Rápido)

# 1. Inicializar configuração
specnote init
# → Pergunta a URL da API (padrão: http://localhost:3000)
# → Pergunta o nome do perfil (padrão: default)

# 2. Fazer login
specnote auth login -e [email protected] -p suasenha

# 3. Verificar se está funcionando
specnote auth me

# 4. IMPORTANTE: Selecionar organização (multi-tenant)
specnote auth switch-org
# → Selecione a organização que deseja trabalhar

# Pronto! Agora você pode usar todos os comandos

⚠️ ATENÇÃO: O SpecNote é multi-tenant. Após o login, você DEVE selecionar uma organização com auth switch-org antes de acessar projetos, tarefas ou outros recursos.

Configuração Inicial

Método 1: Usando o comando init (RECOMENDADO)

# Configuração interativa
specnote init

O comando init irá perguntar:

• URL da API (padrão: http://localhost:3000)
• Nome do perfil (padrão: default)
• Se deseja definir como perfil padrão

Método 2: Configuração manual

# 1. Configurar URL da API
specnote config set --api-url http://localhost:3000 --profile dev
specnote config set --api-url https://api.specnote.com --profile prod

# 2. Fazer Login
specnote auth login -e [email protected] -p senha123

# Login com perfil específico (MUDOU!)
specnote auth login -e [email protected] -p senha --profile user
specnote auth login -e [email protected] -p senha --profile admin
specnote auth login -e [email protected] -p senha --profile dev

⚠️ Nota: O parâmetro mudou de --save-as para --profile para manter consistência

⚠️ Formatos de Data

Ao criar ou atualizar projetos, as datas devem estar no formato ISO 8601 completo:

• Formato correto: 2024-01-15T00:00:00Z
• Formato incorreto: 2024-01-15 (causará erro de validação)

Exemplo:

# ✅ Correto
--start-date "2024-01-15T00:00:00Z"

# ❌ Incorreto
--start-date "2024-01-15"

3. Verificar Configuração

# Listar perfis disponíveis
specnote auth profiles

# Trocar perfil padrão
specnote auth use user

# Usar perfil temporário em comando
specnote --profile admin users list

Comandos Disponíveis

Inicialização (init)

# Configuração inicial interativa
specnote init

# Com parâmetros diretos
specnote init --url http://localhost:3000 --profile local

Configuração (config)

# Definir URL da API
specnote config set --api-url http://localhost:3000/api/v1

# Configurar perfil específico
specnote config set --api-url http://localhost:3000/api/v1 --profile user
specnote config set --api-url https://api.specnote.com/v1 --profile production

# Mostrar configuração
specnote config show           # Mostra config do perfil ativo
specnote config show --all     # Mostra config de todos os perfis

# Limpar configuração
specnote config clear          # Com confirmação
specnote config clear --force  # Sem confirmação
specnote config clear --profile user  # Limpar perfil específico
specnote config clear --all    # Limpar todos os perfis

Autenticação (auth)

Gerencia autenticação e múltiplos perfis. Documentação completa →

# Login
specnote auth login -e [email protected] -p senha
specnote auth login -e [email protected] -p senha --profile admin

# Ver usuário e perfis
specnote auth me
specnote auth profiles
specnote auth use admin

# Logout
specnote auth logout

Usuários (users)

# Operações básicas
specnote users list --search "john"
specnote users show <user-id>
specnote users create -n "Nome" -e "[email protected]" -p "password"
specnote users update <user-id> --active false
specnote users delete <user-id>

Organizações (organizations)

Gerenciamento de empresas/clientes. Documentação completa →

# Listar e buscar
specnote organizations list
specnote orgs list --search "tech"

# Criar e gerenciar
specnote orgs create -n "Tech Corp" -s "tech-corp"
specnote orgs update <id> --website "https://tech.com"
specnote orgs delete <id>

Requisitos (requirements)

Requisitos funcionais e não-funcionais. Documentação completa →

# Listar e buscar
specnote requirements list
specnote specs list                     # Alias
specnote specs list --type FUNCTIONAL
specnote specs list --priority HIGH

# Criar requisito
specnote specs create \
  --project-id <id> --code "RF001" \
  --title "Sistema de autenticação" \
  --type "FUNCTIONAL" --priority "HIGH"

# Atualizar e gerenciar
specnote specs update <id> --status APPROVED
specnote specs delete <id>

Projetos (projects)

Gerenciamento de projetos. Documentação completa →

# Operações básicas
specnote projects list --status ACTIVE
specnote proj show <project-id>
specnote proj create --organization-id <id> --name "Novo Projeto" --slug "novo-projeto"
specnote proj update <id> --budget 75000
specnote proj status <id> COMPLETED
specnote proj delete <id>

# Backup / restore via snapshot YAML (Project + Scopes + Requirements)
specnote proj export <project-id>                              # YAML para stdout
specnote proj export <project-id> --out backups/snap.yaml      # grava no caminho
specnote proj export <project-id> --json                       # JSON em vez de YAML

specnote proj validate snap.yaml --project <project-id>        # dry-run + diff
specnote proj import <project-id> snap.yaml --mode merge       # upsert por code (não deleta)
specnote proj import <project-id> snap.yaml --mode replace --force  # wipe + recreate (bloqueia se houver tasks)

Escopos (scopes)

# Operações básicas
specnote scopes list                          # Lista todos os escopos da organização
specnote scopes list --project-id <id>        # Filtra por projeto
specnote scopes list --json                   # Saída em JSON
specnote scope show <scope-id>
specnote scope create --project-id <id> --name "Autenticação" --original-price 12500
specnote scope close <id>
specnote scope deliver <id>
specnote scope stats

# Nota: A listagem agora mostra ID do escopo e ID do projeto (8 primeiros dígitos)

Tarefas (tasks)

Gerenciamento de tarefas técnicas. Documentação completa →

# Listar e buscar
specnote tasks list
specnote tasks list --status IN_PROGRESS
specnote tasks list --scope-id <id>           # Filtra por escopo (aceita ID parcial de 8 dígitos)
specnote tasks list --project-id <id>         # Filtra por projeto
specnote tasks list --json                    # Saída em JSON
specnote tasks get TASK-001

# Criar tarefa
specnote tasks create \
  --project-id <id> --scope-id <id> --application-id <id> \
  --title "Implementar autenticação" \
  --complexity "MEDIUM" --estimated-hours 8

# Atualizar e gerenciar
specnote tasks update <task-id> --status COMPLETED
specnote tasks doc <task-id>
specnote tasks delete <task-id>

Aplicações (applications)

Aplicações e sistemas desenvolvidos. Documentação completa →

# Operações básicas
specnote applications list --type WEB
specnote apps show <id>
specnote apps create --project-id <id> --type WEB --name "Portal" --price 16000
specnote apps update <id> --status DEPLOYED
specnote apps delete <id>

Requisições HTTP (request)

Interface estilo curl para requisições HTTP. Documentação completa →

# GET
specnote request /api/v1/users
specnote req /api/v1/users --json

# POST, PUT, DELETE
specnote req /api/v1/users --post -d '{"name":"João"}'
specnote req /api/v1/users/123 --put -d '{"active":false}'
specnote req /api/v1/users/123 --delete

# Com pipes
specnote req /api/v1/users --json | jq '.users | length'

Modos de Uso

Multi-Profile (Múltiplos Perfis)

O CLI permite trabalhar com vários perfis simultaneamente:

# Opção 1: Usar --profile em qualquer comando
specnote --profile user users list
specnote --profile admin users create ...

# Opção 2: Trocar perfil padrão
specnote auth use admin
specnote users list  # Usará perfil admin

# Opção 3: Scripts pré-configurados
pnpm sn:user users list
pnpm sn:admin users list

# Opção 4: Variável de ambiente
export SPECNOTE_PROFILE=production
specnote users list

Modo Não-Interativo (Padrão)

Todos os comandos agora funcionam de forma não-interativa, recebendo parâmetros via linha de comando:

specnote users create \
  -n "João Silva" \
  -e "[email protected]" \
  -p "senha123"

Confirmações

Comandos destrutivos solicitam confirmação por padrão, mas podem ser executados com --force:

# Com confirmação
specnote users delete <id>
specnote config clear

# Sem confirmação
specnote users delete <id> --force
specnote config clear --force

Desenvolvimento

Para informações sobre desenvolvimento, arquitetura e contribuição, consulte o Guia Técnico.

Quick Start

# Desenvolvimento local
pnpm cli <comando>

# Build
pnpm build

Troubleshooting

Problemas Comuns

"Cannot connect to server"

# Verifique se o servidor está rodando
cd apps/backend
pnpm dev

# Em outro terminal, tente novamente
specnote auth me

"API endpoint not found" (404)

# Verifique a URL da API
specnote config show

# Se estiver errada, corrija:
specnote config set --api-url http://localhost:3000

"Authentication failed" (401)

# Suas credenciais estão incorretas
# Verifique email e senha e tente novamente
specnote auth login -e [email protected] -p senhaCorreta

"Access denied" após login bem-sucedido

# Este erro ocorre quando você não selecionou uma organização
# O SpecNote é multi-tenant e requer seleção de organização

# 1. Verifique suas organizações disponíveis
specnote organizations list

# 2. Selecione uma organização
specnote auth switch-org
# OU com ID direto:
specnote auth switch-org <organization-id>

# 3. Agora os comandos devem funcionar
specnote projects list
specnote tasks list

Problemas com Perfis

"Profile not found" ou "No active profile"

# Ver quais perfis existem
specnote auth profiles

# Se nenhum perfil existe, fazer login
specnote auth login -e [email protected] -p senha --profile default

# Se perfil existe mas não é o padrão
specnote auth use nome-do-perfil

"Token expired" ou erro 401

# Fazer login novamente no perfil problemático
specnote auth login -e [email protected] -p senha --profile nome-do-perfil

# Ou logout e login
specnote auth logout --profile nome-do-perfil
specnote auth login -e [email protected] -p senha --profile nome-do-perfil

Perfil usando API URL errada

# Verificar configuração do perfil
specnote auth profiles

# Corrigir URL da API
specnote config set --api-url http://localhost:3000/api/v1 --profile nome-do-perfil

# Ou fazer login novamente com URL correta
specnote config set --api-url http://localhost:3000/api/v1 --profile nome-do-perfil
specnote auth login -e [email protected] -p senha --profile nome-do-perfil

Múltiplos perfis confusos

# Ver qual perfil está ativo
specnote auth current

# Ver todos os perfis e suas configurações
specnote auth profiles

# Limpar perfil problemático
specnote auth remove-profile nome-problemático

# Resetar completamente (CUIDADO!)
specnote config clear --all
rm -rf ~/.specnote-cli

Problemas Gerais

Erro de autenticação

# Verificar se o token não expirou
specnote auth me

# Se não funcionar, fazer login novamente
specnote auth login -e [email protected] -p senha

Comando não funciona

# Verificar se API URL está correta
specnote config show

# Testar conectividade com debug
specnote --debug auth me

# Usar perfil específico para testar
specnote --profile nome-do-perfil auth me

Limpar configuração

# Limpar apenas configuração (mantém perfis)
specnote config clear

# Limpar tudo (remove todos os perfis)
specnote config clear --all
rm -rf ~/.specnote-cli

Sistema Multi-Perfis

O CLI suporta múltiplos perfis para trabalhar com diferentes usuários e ambientes. Documentação completa →

Configuração Rápida

# 1. Login com perfis nomeados
specnote auth login -e [email protected] -p senha --profile admin
specnote auth login -e [email protected] -p senha --profile dev

# 2. Usar perfis
specnote --profile admin users list
specnote auth use dev
export SPECNOTE_PROFILE=prod

Suporte a JSON (--json)

Todos os comandos de criação e atualização suportam entrada via JSON através do stdin:

# Criar usuário via JSON
echo '{
  "name": "Maria Santos",
  "email": "[email protected]", 
  "password": "senha123"
}' | specnote users create --json

# Atualizar com JSON (CLI options têm prioridade)
echo '{"name": "Novo Nome"}' | specnote users update <id> --json --active false

# Criar usuário via arquivo JSON
cat user.json | specnote users create --json

Modo Debug (--debug)

Adicione --debug a qualquer comando para habilitar o modo debug:

# Ativa o header X-Debug-Mode em todas as requisições
specnote --debug users create ...
specnote --debug users list

# Funciona com JSON também
echo '{}' | specnote --debug users update <id> --json

Exemplos de Uso

Fluxo Completo do Zero (IMPORTANTE)

# 1. Configurar e fazer login
specnote init --url http://localhost:3000 --profile local
specnote auth login -e [email protected] -p senha

# 2. SEMPRE selecionar organização após login
specnote auth switch-org
# → Escolha a organização desejada

# 3. Agora você pode trabalhar
specnote projects list                    # Lista projetos da organização
specnote tasks list --project-id <id>     # Lista tarefas do projeto
specnote scopes list --project-id <id>    # Lista escopos do projeto

Fluxo completo de gerenciamento de usuários

# 1. Login como admin
specnote auth login -e [email protected] -p senha --profile admin

# 2. Selecionar organização (OBRIGATÓRIO)
specnote auth switch-org

# 3. Criar usuário (usando perfil admin)
specnote --profile admin users create \
  -n "Maria Silva" \
  -e "[email protected]" \
  -p "senha123"

# 4. Verificar criação
specnote --profile admin users list | grep Maria

# 5. Ver detalhes
specnote --profile admin users show <user-id>

Gerenciamento de Organizações

# 1. Criar uma organização
specnote organizations create \
  -n "Tech Solutions" \
  -s "tech-solutions" \
  -d "Empresa de desenvolvimento de software" \
  -w "https://techsolutions.com"

# 2. Listar organizações que você tem acesso
specnote organizations list

# 3. Ver detalhes completos
specnote organizations show <org-id>

# 4. Atualizar informações
specnote organizations update <org-id> \
  --contact-email "[email protected]" \
  --contact-phone "+55 11 99999-9999"

# 5. Usar JSON para criar organização
echo '{
  "name": "Nova Empresa",
  "slug": "nova-empresa",
  "description": "Descrição da empresa",
  "website": "https://nova-empresa.com"
}' | specnote organizations create --json

Gerenciamento de Requisitos

# 1. Listar todos os requisitos de um projeto
specnote requirements list --project-id <project-id>

# 2. Criar requisito funcional
specnote requirements create \
  --project-id <project-id> \
  --code "RF001" \
  --title "Sistema de autenticação" \
  --description "O sistema deve permitir login com email e senha" \
  --type "FUNCTIONAL" \
  --priority "HIGH"

# 3. Criar requisito não-funcional
specnote requirements create \
  --project-id <project-id> \
  --code "RNF001" \
  --title "Performance de carregamento" \
  --description "A página deve carregar em menos de 2 segundos" \
  --type "NON_FUNCTIONAL" \
  --priority "MEDIUM"

# 4. Filtrar requisitos por tipo e prioridade
specnote requirements list \
  --project-id <project-id> \
  --type "FUNCTIONAL" \
  --priority "HIGH"

# 5. Atualizar prioridade de um requisito
specnote requirements update <requirement-id> --priority "URGENT"

# 6. Ver detalhes completos de um requisito
specnote requirements get <requirement-id>

# 7. Criar múltiplos requisitos via JSON
echo '{
  "projectId": "<project-id>",
  "code": "RF002",
  "title": "Sistema de cadastro",
  "description": "O sistema deve permitir cadastro de novos usuários",
  "type": "FUNCTIONAL",
  "priority": "HIGH"
}' | specnote requirements create --json

# 8. Buscar requisitos por termo
specnote requirements list --search "autenticação"

Trabalhar com Múltiplos Perfis

# Configurar perfis
specnote auth login -e [email protected] -p senha --profile user
specnote auth login -e [email protected] -p senha --profile admin

# User: Ver seus próprios dados
specnote --profile user auth me

# Admin: Gerenciar usuários
specnote --profile admin users list
specnote --profile admin users create ...

# Scripts rápidos
pnpm sn:admin users list
pnpm sn:user auth me
pnpm sn:admin requirements list
pnpm sn:admin requirements create --project-id <id> --code RF001 --title "Test" --description "Test req" --type FUNCTIONAL

Documentar Tarefas com Markdown

# 1. Listar tarefas com IDs completos
specnote tasks list --full-id

# 2. Buscar ID pelo código da task
specnote tasks get-id TASK-001
# Output: 02d3f230-6461-446f-85f0-a27aaeae123d

# 3. Adicionar documentação de arquivo
specnote tasks update-doc 02d3f230-6461-446f-85f0-a27aaeae123d --file docs/task-001.md

# 4. Adicionar documentação via editor
specnote tasks update-doc TASK-001

# 5. Ver documentação
specnote tasks doc TASK-001

# 6. Pipeline com markdown
cat <<EOF | specnote tasks update-doc TASK-001 --stdin
# Documentação da Task

## Visão Geral
Esta task implementa a funcionalidade X

## Detalhes Técnicos
- Tecnologia: React + TypeScript
- Padrão: Repository Pattern
- Testes: Jest + Testing Library

## Estimativas
- Backend: 8h
- Frontend: 8h
- Total: 16h
EOF

Usar JSON para automação

# Script para criar múltiplos usuários
for i in {1..5}; do
  echo "{
    \"name\": \"User $i\",
    \"email\": \"[email protected]\",
    \"password\": \"senha123\"
  }" | specnote users create --json
done

# Pipeline com jq
cat users.json | jq -c '.[]' | while read item; do
  echo "$item" | specnote users create --json
done

Debug Mode para troubleshooting

# Ver logs detalhados de uma operação
specnote --debug users create \
  -n "Debug User" \
  -e "[email protected]" \
  -p "senha123"

# Combinar debug com JSON
echo '{"name": "Updated Name"}' | specnote --debug users update <id> --json

Futuros Comandos (Roadmap)

Apps (apps)

• specnote apps list - Listar aplicações do projeto
• specnote apps create - Criar nova aplicação
• specnote apps update <id> - Atualizar aplicação

Packages (packages)

• specnote packages list - Listar pacotes do projeto
• specnote packages create - Criar novo pacote
• specnote packages update <id> - Atualizar pacote

Expertise (expertise)

• specnote expertise list - Listar especialidades da organização
• specnote expertise create - Criar nova especialidade

Análise de Valor (value-analysis)

• specnote analysis create - Criar análise de valor
• specnote analysis list - Listar análises
• specnote analysis show <id> - Ver detalhes da análise
• specnote analysis report <id> - Gerar relatório de ROI