Prevu CLI

O que Prevu CLI faz?

O Prevu provisiona uma VM Linux persistente na qual você pode fazer SSH, expor portas e acessar via URL pública. A CLI prevu é a superfície suportada (sem ferramentas de infraestrutura).

Esta habilidade é a referência: instalação, mapa de comandos, contrato de saída, códigos de saída, com detalhes mais aprofundados em references/*.md. Para fluxos de trabalho de vários passos voltados ao usuário (como espelhar o desenvolvimento local para uma visualização revisável em telefone, compartilhar um branch WIP), consulte a habilidade prevu-flows - carregue-a quando o usuário descrever um cenário em vez de um único comando.

Instalação + login

npm install -g @prevu/cli
prevu --version              # 0.2.0+ (URLs apenas com slug e env exec precisam de 0.2.0+)
prevu auth login             # cole um token de https://app.prevu.cloud/keys

Requer Node >= 20. O token é armazenado em ~/.prevu/config.json (modo 0600).

Para CI / não-TTY:

export PREVU_TOKEN=prv_...

Ordem de resolução: flag --token -> variável de ambiente PREVU_TOKEN -> ~/.prevu/config.json.

PREVU_API_URL padrão é https://app.prevu.cloud. Substitua com --api-url apenas para APIs Prevu auto-hospedadas.

Mapa de comandos

Namespace	Comando	Detalhe em
auth	login / logout / whoami	references/auth.md
env	list, get, create, destroy	references/env.md
env	wait	references/env.md + references/lifecycle.md
env	ssh, ssh-command, exec	references/env.md
env	urls	references/env.md
env	service start/list/logs/restart/stop	references/env.md
env	expose, unexpose	references/env.md
keys	list	references/keys.md

Execute prevu <namespace> --help para ajuda inline.

Contrato de saída - sempre use --format json ao analisar

A saída padrão é uma tabela legível para humanos; para qualquer chamada scriptada, use --format json. O envelope é fixo:

// sucesso
{ "data": { ... } }
// falha
{ "error": { "type": "auth", "message": "...", "hint": "..." } }

NO_COLOR=1 ou --no-color remove ANSI no modo tabela. JSON é sempre sem cores.

Códigos de saída (analise estes, não o texto de stderr)

Código	Tipo	O que significa
0	sucesso	continue
1	genérico	imprima e pare
2	uso	flags inválidas - corrija e tente novamente
3	auth	diga ao usuário para executar prevu auth login
4	não_encontrado	env/chave não existe; crie ou escolha outro
5	conflito	já existe / status errado - geralmente inofensivo
6	limite_taxa	aguarde >=30s e tente novamente
7	servidor	transitório; tente novamente uma vez
8	tempo_esgotado	env wait expirou - abra o painel

Esboço de recuperação idiomática:

prevu env get meu-projeto --format json >/dev/null 2>&1
case $? in
  0) ;;                                    # existe
  4) prevu env create meu-projeto --format json ;;
  3) echo "Execute \`prevu auth login\`" >&2; exit 1 ;;
  *) exit 1 ;;
esac

Regras rígidas - por favor, não quebre estas

1. Ambientes são produtos pagos persistentes. Reutilize-os deliberadamente; nunca destrua automaticamente por TTL ou fim de sessão.
2. Um ambiente por projeto, não por tarefa. Reutilize o mesmo slug entre sessões; o usuário retorna ao mesmo espaço de trabalho.
3. Use exposição HTTPS para prévias no navegador (padrão). O modo TCP é para serviços não-HTTP como Postgres.
4. Imprima URLs publicamente em destaque. O usuário geralmente está no celular; não enterre a URL na saída do shell.
5. Use env service para processos de aplicação de longa duração. Não escreva manualmente nohup, arquivos PID ou comandos pkill -f genéricos.
6. A CLI/API é a única superfície suportada. Não tente usar ferramentas de infraestrutura.

Quando carregar detalhes mais aprofundados

• references/auth.md - fluxos de login, onde o token reside, recuperação do código de saída 3.
• references/env.md - todos os subcomandos de env com entradas, exemplos e regras de resolução de chave SSH.
• references/keys.md - modelo de chave SSH salva, deduplicação, quando --ssh-key-id economiza digitação.
• references/lifecycle.md - máquina de estados, quando wait retorna e orientação para ações destrutivas.
• references/troubleshooting.md - modos de falha concretos e suas correções.

Quando NÃO carregar esta habilidade

• Edições locais puras de arquivos ou trabalho de repositório somente leitura - Prevu é para executar código remotamente.
• Deploys de produção / CI - Prevu é staging.
• Qualquer coisa onde o usuário disse explicitamente "fique no meu laptop."

Cenários de fluxo de trabalho estão em prevu-flows

Se o usuário solicitar espelhar meu desenvolvimento para meu telefone, me permita visualizar do celular, compartilhar este branch como URL, estou longe do teclado, continue codificando - carregue a habilidade prevu-flows em vez de (ou além de) esta. Esses fluxos conectam os comandos aqui em um loop de vários passos com os padrões corretos.