CLI iugu

A CLI iugu é a linha de comando do Console para desenvolvedores e seus agentes de código: cria, configura, testa e publica aplicativos, pede credenciais, acompanha aprovações e chama ações de apps provedores — no terminal ou dentro de uma sessão do Claude Code, Codex, Cursor e similares. Toda saída tem um modo --json estável e códigos de saída com significado, e as mudanças sensíveis passam pelo mesmo circuito de aprovação humana do Console (veja Agentes e aprovações).

O código é aberto (MIT) em github.com/iugu/cli; as releases são assinadas e publicadas em quatro canais.

Instalar

brew install iugu/tap/iugu                                                          # macOS e Linux (Homebrew)
curl -fsSL https://raw.githubusercontent.com/iugu/cli/main/install.sh | sh          # qualquer Unix
scoop bucket add iugu https://github.com/iugu/scoop-bucket && scoop install iugu    # Windows
npx @iugu/cli --help                                                                 # via npm, sem instalar

Confira com iugu --version. Os binários são para macOS, Linux e Windows (amd64 e arm64); completions para bash, zsh e fish acompanham o Homebrew e o arquivo da release.

Entrar

iugu login                    # abre o navegador: login no Console + consentimento (escopos × áreas de trabalho)
iugu login --no-browser       # imprime a URL para abrir em outra máquina
iugu auth status --json       # quem está logado, escopos, áreas de trabalho consentidas
iugu me                       # a pessoa e suas áreas de trabalho
iugu workspace use <id>       # área de trabalho padrão dos comandos seguintes
iugu logout                   # revoga o consentimento no servidor e esquece a credencial local

O login é um fluxo OAuth 2.1 com PKCE contra https://identity.iugu.com; o token de atualização fica no chaveiro do sistema operacional (macOS Keychain, Secret Service, Gerenciador de Credenciais do Windows) e, onde não há chaveiro — Linux sem sessão gráfica, contêineres — em ~/.config/iugu/credentials.json com permissão 0600 (a CLI avisa uma vez). IUGU_TOKEN=<token de deploy> no ambiente vence qualquer login gravado e nunca toca o disco.

Cada instalação da CLI é um portador de credencial próprio: aparece em Agentes conectados com o nome da máquina e pode ser revogada individualmente.

Cinco minutos

iugu login
iugu me
iugu app init --name "Acme Invoices" --workspace <id da área de trabalho de desenvolvimento>
#   → cria o app (privado, rascunho), instala na área de trabalho, pede uma credencial restrita a ela
#     (uma aprovação humana: saída 5 com approval.url) e escreve iugu.toml
iugu changeset wait <id> --write-env .env.local        # espera a aprovação; o segredo vai para .env.local (0600)
iugu app permissions set --implemented invoice.create,invoice.read --grant-scopes informations
iugu test-principal create --name qa                   # principal temporário com papéis ⊆ os seus, 1 h
iugu verify --principal temp:… --action acme-invoices:invoice.create
iugu app env --format fly                              # variáveis não secretas para o alvo de deploy
iugu changeset create --op 'oauth.update:{"url":"https://acme.example","callbacks":["https://acme.example/oauth/callback"]}' \
     --op 'listing.publish:{"public":true,"draft":false}' --submit --wait

O passo a passo comentado — pelo Console e pela CLI — está em Criar um aplicativo.

Comandos

Flags globais: --json, --jq <expressão>, --api, --profile, --credentials-store keyring|file|ephemeral, --idempotency-key, --yes, --agent auto|yes|no. Os comandos que geram aprovação aceitam --wait, --timeout, --write-env <arquivo> e --exec "<comando> {secret}".

Códigos de saída

Para agentes de código

A CLI carrega o seu próprio roteiro para agentes: iugu docs imprime a skill completa (o caminho recomendado, o que exige uma pessoa, como esperar aprovações, política de segredos, alvos de deploy, rotação de credenciais, sandboxes) e iugu docs --llms um resumo curto; iugu docs <tópico> mostra uma seção (golden-path, tiers, secrets, deploying, rotation, integration, actions, billing, sandboxes, exit-codes, approval-policy).

iugu agent setup --all      # escreve a entrada do Iugu for AI (MCP) e a skill para Claude Code, Codex, OpenCode, Cursor e VS Code
iugu agent setup --print    # mostra os trechos sem gravar

Regras que a skill ensina ao agente — e que valem para qualquer automação:

• chamar sempre com --json e decidir pelo código de saída e por error.code;
• nunca pedir um segredo à pessoa nem ecoá-lo: --write-env <arquivo> grava com 0600, --exec "<comando> {secret}" substitui em processo;
• entregar approval.url à pessoa e esperar com changeset wait — a aprovação é dela, não do agente;
• um comando por chamada de shell, para que o próprio harness veja o código de saída.

Deploy e CI

iugu app env --format railway            # ou fly, netlify, vercel, dotenv, json: as variáveis públicas do app
iugu changeset wait <id> --exec 'fly secrets set IUGU_CLIENT_SECRET={secret}'   # o segredo vai direto ao cofre do alvo
iugu app deploy-tokens create --scope oauth,rotate_self --expires 24h            # token para o pipeline (aprovação)
IUGU_TOKEN=<token> iugu app credentials rotate --id <credencial> --wait --exec '…'   # no CI: rotação sem janela

Um token de deploy age sobre um único app e só para URL e callbacks (oauth), filtro por IPs (ip_whitelist) e rotacionar a própria credencial (rotate_self).

Contrato e compatibilidade

As formas do --json seguem o contrato publicado da Lifecycle API — api-v1.yaml — e a skill embutida é atualizada a cada mudança do contrato. Antes da versão 1.0 as formas podem mudar entre releases; as notas de cada release em github.com/iugu/cli/releases listam as mudanças. Problemas de segurança: veja o SECURITY.md do repositório.