Shade Cloud CLI

CLI oficial da Shade Cloud para autenticar, listar projetos, consultar status, enviar deploys por ZIP e ler logs pela API pública.

Instalação

npm install -g @shadecloud/cli

Requer Node.js 20.10 ou superior.

Login

Crie uma API key no painel da Shade Cloud em Configurações / API pública e habilite os escopos necessários:

• projects:read
• projects:write
• deployments:read
• deployments:write
• logs:read

shade login

A API key fica salva no storage local do usuário via conf. Ela nunca é escrita em .shadeconfig e nunca é exibida inteira no terminal.

Também é possível usar variável de ambiente:

SHADE_API_KEY=shade_sk_xxx shade projects

Primeiro uso

Dentro da pasta do seu projeto, rode:

shade init

O CLI vai perguntar como conectar esta pasta à Shade Cloud:

• Usar um projeto que já existe na Shade Cloud: escolha na lista e o CLI salva o ID no .shadeconfig.
• Criar um novo projeto a partir do GitHub: informe usuário/repositório e branch.
• Colar o ID de um projeto que você já tem: use quando alguém já te passou um ID como proj_123.
• Configurar este diretório agora e vincular o projeto depois: cria só os arquivos locais. Depois rode shade deploy --project proj_xxx.

Deploy

Fluxo principal:

shade deploy

Opções úteis:

shade deploy --project proj_xxx
shade deploy --cwd ./apps/web
shade deploy --message "release inicial"
shade deploy --no-confirm
shade deploy --dry-run

O deploy detecta o diretório atual, lê .shadeconfig, aplica .shadeignore, prepara arquivos em etapas com listr2, cria um ZIP temporário e envia para:

POST /projects/{projectId}/deployments/upload

Por padrão, arquivos sensíveis e pesados são excluídos, incluindo node_modules, .git, dist, build, .next, .cache, .turbo, logs, .env, .env.*, arquivos temporários e logs. .env.example é preservado.

Use --dry-run para ver checklist, card de resumo, arquivos incluídos, tamanho aproximado e destino sem enviar nada.

Configuração

Formato local:

{
  "projectId": "proj_xxx",
  "name": "minha-api",
  "source": {
    "type": "local"
  },
  "deploy": {
    "include": [],
    "exclude": []
  }
}

Formato GitHub:

{
  "projectId": "proj_xxx",
  "name": "minha-api",
  "source": {
    "type": "github",
    "repository": "usuario/repositorio",
    "branch": "main"
  }
}

O arquivo é validado com zod e campos extras retornados pela API são tolerados no client.

.shadeignore

Sintaxe compatível com .gitignore.

node_modules
.git
dist
build
.next
.cache
.turbo
.env
.env.*
*.log
.DS_Store

Comandos

shade --help
shade help deploy
shade lang set pt
shade lang clear
shade login
shade logout
shade whoami
shade init
shade projects
shade projects list
shade ls
shade status --project proj_xxx
shade deploy
shade logs --project proj_xxx --deployment dep_xxx
shade cancel --project proj_xxx --deployment dep_xxx

A ajuda é localizada. Para salvar um idioma padrão neste computador, use shade lang set pt ou shade lang set en.

Para comandos que precisam de projeto, como status, logs e cancel, o --project é opcional quando existe projectId no .shadeconfig. Se o CLI não encontrar um projeto configurado, ele pergunta se você quer escolher um projeto da sua conta ou colar o ID manualmente.

Variáveis de ambiente

• SHADE_API_KEY: API key usada no header Authorization: Bearer.
• SHADE_API_URL: URL base da API. Default: https://api.acq.lat/public/v1.
• SHADE_LANG: pt ou en. Sobrescreve temporariamente o idioma salvo. Sem valor salvo, o CLI usa o idioma do sistema quando possível.

Também há flags globais:

shade --api-url https://api.acq.lat/public/v1 projects

Para salvar o idioma padrão do usuário:

shade lang set pt
shade lang set en
shade lang clear

UX do terminal

O CLI usa:

• picocolors para cores e destaque.
• ora para spinners em operações curtas.
• listr2 para checklist visual do fluxo de deploy.
• @inquirer/prompts para inputs, passwords, confirmações e seleções.
• cli-table3 para tabelas Unicode.
• boxen para cards de resumo.
• terminal-link para URLs clicáveis quando o terminal suporta.

Troubleshooting

API key inválida ou revogada

shade login

Ou:

SHADE_API_KEY=shade_sk_xxx shade whoami

Escopo insuficiente

Revise os escopos no painel da Shade Cloud. Deploy por ZIP requer deployments:write; listagem/status requer projects:read; logs requerem logs:read.

ID do projeto não encontrado

shade init
shade deploy --project proj_xxx

Segurança

• .shadeconfig não armazena API key.
• .env e .env.* nunca entram no ZIP por padrão.
• Tokens são mascarados como shade_sk_****abcd.
• Headers sensíveis não são impressos em erros.
• O ZIP de deploy é temporário e removido após o upload.

Desenvolvimento

npm install
npm run dev -- --help
npm run build
npm run typecheck
npm run lint
npm test

Publicação:

npm run prepublishOnly
npm publish --access public