Apresentando a Nulvless CLI

Hoje estamos lançando a Nulvless CLI, uma linha de comando open source para projetos Nulvless. Ela gerencia environments, Edge Functions e suas secrets pelo terminal, e foi pensada desde o primeiro comando para ser usada por agentes de IA, além de por você.

npm install --global nulvless
nulvless login

O pacote instala dois comandos equivalentes, nulvless e o mais curto nulv. O código está no GitHub sob licença MIT.

Set up the Nulvless CLI for this project.

Read https://www.nulvless.com/llms.mdx/docs/cli/content.md first. It documents
the real commands, so do not guess them.

- Check that `npx nulvless whoami --json` works. If it exits with code 2, ask me
  to run `npx nulvless login` in my own terminal and wait.
- Ask me for the organization and project slugs, and pass them as `--org` and
  `--project` on every command.
- Always pass `--json` and read errors from the JSON line on stderr.
- Never print secret values. Set secrets with KEY=VALUE only when I give you the
  value.

Por que uma CLI agora

Cada vez mais o código que conversa com a Nulvless é escrito com um agente no meio. Agentes são bons em ler documentação e rodar comandos, e ruins em clicar pelo console. Até agora, toda mudança fora do seu código, como um environment novo ou uma secret trocada, significava sair do editor e ir para o navegador. A CLI leva essas ações para a interface que você e o seu agente já compartilham: o terminal.

O que ela faz hoje

A primeira versão cobre o trabalho do dia a dia em um projeto:

nulvless whoami                                   # conta e organizações
nulvless environments list --project shop         # environments de um projeto
nulvless environments create staging              # um environment novo
nulvless functions list                           # Edge Functions
nulvless functions deployments checkout           # histórico de deploys
nulvless secrets set STRIPE_SECRET_KEY --function checkout
nulvless docs sdk/auth                            # uma página da documentação em Markdown

As secrets recebem cuidado especial. secrets list mostra os nomes e nunca os valores. secrets set KEY sem valor pede o valor sem exibi-lo, então ele nunca vai parar no histórico do shell, e salvar uma secret faz um novo deploy da função com ela. Nomes que a Nulvless reserva para valores injetados, como qualquer um começando com NULVLESS_, são recusados antes de qualquer request.

Feita para agentes

Projetar para agentes acabou sendo o mesmo que projetar para scripts e para pessoas com pressa. Algumas regras guiaram cada comando:

• A documentação a um comando de distância. nulvless docs imprime o índice de todas as páginas e nulvless docs <path> imprime uma página em Markdown. O agente lê a API real antes de escrever uma linha, em vez de adivinhar nomes de métodos.

• Saída que um agente consegue ler. Todo comando aceita --json. Os resultados vão para o stdout e o resto para o stderr, então o JSON nunca se mistura com mensagens de progresso. Falhas também são JSON:

  {"error":{"message":"You are not signed in.","hint":"Run `nulvless login` to sign in.","exitCode":2}}

• Nunca travada em uma pergunta. Fora de um terminal a CLI nunca espera por entrada. Se precisar de uma organização ou projeto, ela falha e diz qual flag passar. Comandos destrutivos exigem --yes.

• Erros com próximo passo. Todo erro traz uma dica. Os códigos de saída são estáveis: 0 para sucesso, 1 para falha, 2 quando você precisa entrar ou não tem permissão.

Login sem copiar tokens

nulvless login usa o mesmo OAuth Server que você pode ligar nos seus próprios projetos. A CLI abre a tela de consentimento no navegador, você aprova, e o navegador devolve a sessão para a CLI na sua máquina. O fluxo é authorization code com PKCE e um endereço de loopback de uso único, o que o OAuth 2.1 recomenda para apps nativos.

A sessão fica no chaveiro do sistema, com um arquivo legível só pelo seu usuário como alternativa, e é renovada automaticamente. Em CI, defina NULVLESS_TOKEN e nenhum navegador entra na história.

O que vem a seguir

Esta versão é a base. Agora estamos trabalhando para criar e fazer deploy de Edge Functions a partir do seu repositório, para que o ciclo inteiro, de escrever uma função a colocá-la no ar, rode pelo terminal, por você ou pelo seu agente.

A CLI é open source, e issues e pull requests são bem-vindos no GitHub. Para começar, leia a documentação da CLI ou rode:

npx nulvless --help