upuai-cli
Faça deploy, gerencie e monitore suas aplicações Upuai Cloud diretamente pelo terminal. Um CLI para controlar toda sua infraestrutura cloud.
Introdução
upuai-cli é a interface de linha de comando oficial do Upuai Cloud. Permite fazer deploy de aplicações, gerenciar variáveis de ambiente, visualizar logs, escalar serviços e controlar todos os aspectos da sua infraestrutura — tudo sem sair do terminal.
Recursos principais
- Deploy zero-config a partir de qualquer diretório
- Visualização de logs em tempo real com filtros
- Gerenciamento de variáveis de ambiente e secrets
- Configuração e vinculação interativa de projetos
- Suporte a múltiplos ambientes (production, staging, development)
- Múltiplos formatos de saída (table, JSON, text)
- Acesso direto a Postgres: psql interativo, pg_dump e pg_restore via endpoint público
- Subshell e run com env vars do serviço injetadas (paridade com Railway)
Instalação
Instale o upuai-cli usando seu gerenciador de pacotes preferido.
Homebrew (macOS / Linux)
$ brew tap saiph-ti/upuai-cli
$ brew install upuaiScoop (Windows)
> scoop bucket add upuai https://github.com/saiph-ti/scoop-upuai-cli
> scoop install upuaiDirect download (Linux / macOS)
$ curl -sSfL https://github.com/saiph-ti/upuai-cli/releases/latest/download/upuai_linux_x86_64.tar.gz | tar -xz
$ sudo mv upuai /usr/local/bin/$ upuai version
upuai/0.0.2 (206c727) built 2026-04-23T18:37:12ZAutenticação
Autentique-se no Upuai Cloud para acessar seus projetos e recursos.
| Comando | Descrição |
|---|---|
| upuai login | Autenticar via navegador. Abre uma janela do navegador para login OAuth e armazena as credenciais localmente. |
| upuai logout | Limpar credenciais armazenadas e revogar a sessão atual. |
| upuai whoami | Exibir o usuário autenticado, organização e projeto padrão. |
$ upuai login
▸ Opening browser for authentication...
✓ Logged in as gabriel@upuai.com.br
Organization: Upuai Labs
Default project: my-app$ upuai whoami
User: gabriel@upuai.com.br
Organization: Upuai Labs
Default project: my-appGerenciamento de Projetos
Inicialize novos projetos, vincule diretórios e gerencie seus projetos no Upuai Cloud.
| Comando | Alias | Descrição |
|---|---|---|
| upuai init | — | Inicializar um novo projeto no diretório atual. Auto-detecta o framework e cria uma configuração local com as definições do projeto. |
| upuai link | — | Vincular o diretório atual a um projeto existente no Upuai Cloud. Seletor interativo permite escolher entre seus projetos. |
| upuai unlink | — | Desvincular o diretório atual do projeto. Remove o arquivo local .upuai/config.json. |
| upuai list | upuai ls | Listar todos os seus projetos com nome, ID, status e data de criação. |
| upuai open | — | Abrir o projeto vinculado no navegador. Navega diretamente para o dashboard do projeto. |
| upuai delete | — | Deletar o projeto vinculado. Esta ação é irreversível e requer dupla confirmação (re-digitação do nome). |
| upuai status | — | Exibir o status do projeto incluindo serviços, URLs, estado do deploy e uso de recursos. |
$ upuai init
? Project name: my-app
? Detected: Node.js (Next.js)
? Build command: pnpm run build
? Start command: pnpm start
✓ Project ready to deploy$ upuai link
? Select a project:
❯ my-app (production)
api-service (staging)
landing-page (production)
✓ Linked to my-app$ upuai list
NAME ID STATUS CREATED
my-app prj_abc123 Active 2d ago
api-service prj_def456 Active 1w ago
landing-page prj_ghi789 Active 2w ago$ upuai status
Project: my-app (production)
URL: https://my-app.upuai.com.br
Services:
web ● Running 2/2 instances CPU: 23% MEM: 412Mi
worker ● Running 1/1 instances CPU: 8% MEM: 256Mi
Last deploy: 2h ago (v1.4.2) by gabriel@upuai.com.brDeploy
Faça deploy da sua aplicação no Upuai Cloud. Suporta deploy zero-config, watch mode, rollbacks, redeploys e promoção entre ambientes.
| Comando | Alias | Descrição |
|---|---|---|
| upuai deploy | upuai up | Fazer deploy do diretório atual no Upuai Cloud. Auto-detecta linguagem, framework e configurações de build. |
| upuai deploy --watch | — | Iniciar watch mode. Faz redeploy automaticamente quando arquivos mudam (debounce de 500ms). |
| upuai redeploy | — | Refazer o deploy do último deployment. Reconstrói e reinicia com a mesma configuração. |
| upuai rollback | — | Reverter para o deploy anterior bem-sucedido. Troca instantânea sem downtime. |
| upuai promote | — | Promover o deploy atual de staging para produção. |
| upuai down | — | Remover o último deployment e parar o serviço. Requer confirmação. |
| Flag | Curta | Tipo | Padrão | Descrição |
|---|---|---|---|---|
| --watch | -w | boolean | false | Ativar watch mode para redeploy automático ao mudar arquivos. |
$ upuai deploy
▸ Uploading my-app (3.2 MB)
▸ Building with upuaipack...
▸ Build completed in 42s
▸ Deploying (rolling)...
▸ Health check passed
✓ Deployed to https://my-app.upuai.com.br
Deploy ID: dep_abc123
Duration: 1m 12s$ upuai deploy --watch
◉ Watching for changes...
▸ src/index.ts changed — redeploying...
✓ Deployed in 38s
◉ Watching for changes...$ upuai rollback
✓ Rolled back to previous deployment (dep_xyz789)$ upuai promote
▸ Promoting staging → production
▸ Deployment dep_stg_001 → dep_prd_002
✓ Production updated. URL: https://my-app.upuai.com.br$ upuai down
▸ Removing deployment for web...
✓ Service stopped. No instances running.Operações de Serviço
Gerencie serviços individuais dentro do seu projeto. São comandos de nível superior que operam no serviço vinculado.
| Comando | Descrição |
|---|---|
| upuai add | Adicionar um novo serviço ao projeto via wizard interativo. Suporta tipos app, database, Redis, function, bucket, volume e Docker. |
| upuai ps | Listar os processos do serviço vinculado (web/worker/clock/release) declarados via Procfile ou upuai.toml [processes.*], com tipo, réplicas e comando. |
| upuai restart | Reiniciar o serviço vinculado. Requer confirmação (pule com --yes). Use --process <nome> para reiniciar um único processo de um app multi-processo. |
| upuai logs | Visualizar logs do serviço vinculado. Exibe as linhas de log mais recentes. Use --process <nome> para filtrar por um processo. |
| upuai scale <count> | <proc>=<n> ... | Escalar o serviço vinculado. Passe um número para escalar o processo web, ou pares por-processo como `web=2 worker=1` num app multi-processo (Procfile). |
| upuai run <command> | Executar um comando local com as variáveis de ambiente do serviço injetadas. O separador `--` é opcional — use-o quando o seu comando tiver flags que conflitam com as do upuai. Variáveis secretas são mascaradas e não injetadas. |
| upuai shell | Abrir um subshell interativo com as variáveis do serviço injetadas (paridade com `railway shell`). Detecta $SHELL no Unix e %COMSPEC% no Windows. |
| Flag | Curta | Tipo | Padrão | Descrição |
|---|---|---|---|---|
| --lines | -n | integer | 100 | Número de linhas de log a buscar (para upuai logs). |
| --service | -s | string | — | Nome, slug ou ID do serviço (sobrescreve o serviço vinculado). Disponível em `run`, `shell` e `variables`. |
| --process | — | string | — | Mira um único processo de um serviço multi-processo (Procfile). Disponível em `logs`, `restart` e `ssh`. Liste com `upuai ps`. |
| --shell | — | string | — | Caminho do binário do shell (default: $SHELL ou cmd.exe). Apenas em `shell`. |
$ upuai add
? Service type:
❯ App
Database (PostgreSQL, MySQL, MongoDB)
Redis
Function
Bucket
Volume
Docker
? Service name: api
✓ Service api added to project$ upuai logs -n 50
[web] 2026-02-14T10:23:01Z GET /api/users 200 12ms
[web] 2026-02-14T10:23:02Z GET /api/health 200 2ms
[web] 2026-02-14T10:23:05Z POST /api/orders 201 45ms
[web] 2026-02-14T10:23:08Z GET /api/users/42 200 8ms$ upuai ps
NAME TYPE REPLICAS COMMAND
web web 2 bundle exec puma
worker worker 1 bundle exec sidekiq
clock clock 1 bundle exec clockwork clock.rb$ upuai scale 5
▸ Scaling web: 2 → 5 instances
✓ web scaled to 5 instances
$ upuai scale web=2 worker=3
▸ Scaling web: 5 → 2 · worker: 1 → 3
✓ scaled$ upuai restart
▸ Restarting web...
✓ Service restarted$ upuai run npx prisma migrate deploy
▸ Injecting 5 environment variable(s)
▸ Running: npx prisma migrate deploy
Applying migration: 20260214_add_orders
✓ Migration complete$ upuai run -s api -- env | grep DATABASE_URL
DATABASE_URL=postgres://user:****@cmocv2dv6001i01o2ul89crrc.db.upuai.cloud:5432/app$ upuai shell -s api
ℹ Spawning /bin/zsh with 7 variable(s) from service
ℹ Type 'exit' to leave the subshell
api % printenv DATABASE_URL
postgres://user:****@cmocv2dv6001i01o2ul89crrc.db.upuai.cloud:5432/app
api % exitBanco de Dados
Conecte-se diretamente ao Postgres do serviço vinculado, faça dump e restore via endpoint público da plataforma. Equivale ao `railway connect` + `railway run pg_dump` em um único comando gerenciado.
| Comando | Descrição |
|---|---|
| upuai db connect | Abrir uma sessão psql interativa contra o banco vinculado via endpoint público. Requer psql instalado localmente (postgresql-client / libpq). |
| upuai db connect --print | Imprimir a connection string pública (URI completo + host/porta) sem abrir o psql. Útil para scripts. |
| upuai db backup --out file.dump | Rodar pg_dump contra o endpoint público e salvar em formato custom no arquivo informado. Requer pg_dump local. |
| upuai db restore -f file.dump | Restaurar um .dump via pg_restore. Por padrão usa --clean --if-exists --no-owner --no-acl. Requer confirmação (pule com --yes). |
| Flag | Curta | Tipo | Padrão | Descrição |
|---|---|---|---|---|
| --out | — | string | — | Arquivo de saída do pg_dump (obrigatório em `db backup`). |
| --file | -f | string | — | Arquivo .dump de entrada (obrigatório em `db restore`). |
| — | boolean | false | Em `db connect`, imprime a connection string e sai sem abrir o psql. | |
| --enable | — | boolean | false | Habilita o endpoint público sem prompt se ainda estiver desabilitado. |
$ upuai db connect
▸ Fetching access status...
✓ public access enabled at cmocv2dv6001i01o2ul89crrc.db.upuai.cloud:5432
ℹ opening psql → cmocv2dv6001i01o2ul89crrc.db.upuai.cloud:5432
psql (16.4)
SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384)
Type "help" for help.
app=> \dt
List of relations
Schema | Name | Type | Owner
--------+-----------+-------+----------
public | users | table | postgres
public | orders | table | postgres
(2 rows)
app=> \q$ upuai db connect --print
Host: cmocv2dv6001i01o2ul89crrc.db.upuai.cloud Port: 5432
postgres://app_user:****@cmocv2dv6001i01o2ul89crrc.db.upuai.cloud:5432/app?sslmode=require$ upuai db backup --out backup-2026-04-28.dump
ℹ running pg_dump → backup-2026-04-28.dump
✓ backup written: backup-2026-04-28.dump (12834567 bytes)$ upuai db restore -f backup-2026-04-28.dump
? Restore backup-2026-04-28.dump into the linked database? This rewrites matching objects. Yes
ℹ running pg_restore from backup-2026-04-28.dump
✓ restore completeAmbientes
Gerencie ambientes do projeto. O comando environment suporta troca interativa e subcomandos para controle completo.
| Comando | Alias | Descrição |
|---|---|---|
| upuai environment | upuai env | Trocar o ambiente ativo interativamente usando um menu de seleção. |
| upuai env list | — | Listar todos os ambientes com nome, ID, status ativo e flag de efêmero. |
| upuai env switch <name> | — | Trocar o ambiente ativo para os próximos comandos. |
| upuai env new <name> | — | Criar um novo ambiente. |
| upuai env delete <name> | — | Deletar um ambiente. Requer confirmação (pule com --yes). |
$ upuai env
? Select environment:
❯ production (active)
staging
development
✓ Active environment: production$ upuai env list
NAME ID ACTIVE EPHEMERAL
production env_abc123 ● No
staging env_def456 No
development env_ghi789 No$ upuai env switch staging
✓ Active environment: staging$ upuai env new preview
✓ Environment preview createdConfiguração
Gerencie variáveis de ambiente e domínios customizados para seus serviços.
| Comando | Alias | Descrição |
|---|---|---|
| upuai variables list | upuai vars list | Listar todas as variáveis de ambiente. Valores secretos são mascarados. |
| upuai variables set KEY=VALUE | — | Definir uma ou mais variáveis de ambiente. Aceita múltiplos pares KEY=VALUE. |
| upuai variables delete <KEY> | — | Deletar uma variável de ambiente. Requer confirmação (pule com --yes). |
| upuai domain list | upuai domains list | Listar todos os domínios customizados com tipo, status e ID. |
| upuai domain add <domain> | — | Adicionar um domínio customizado. Exibe os registros DNS que precisam ser configurados. |
| upuai domain delete <domain-id> | — | Deletar um domínio customizado. Requer confirmação (pule com --yes). |
$ upuai vars set DATABASE_URL=postgres://user:pass@host/db NODE_ENV=production
✓ 2 variables set$ upuai vars list
NAME VALUE SECRET
DATABASE_URL postgres://user:*** Yes
REDIS_URL redis://localhost:6379 No
API_KEY **** Yes
NODE_ENV production No$ upuai domain add app.example.com
▸ Configure these DNS records:
Type Name Value
CNAME app.example.com my-app.upuai.com.br
✓ Domain added. Configure DNS and it will be verified automatically.$ upuai domains list
DOMAIN TYPE STATUS ID
my-app.upuai.com.br Auto ● Active dom_abc123
app.example.com Custom ● Active dom_def456
api.example.com Custom ○ Pending dom_ghi789Utilitários
Comandos utilitários para gerenciar o próprio CLI.
| Comando | Descrição |
|---|---|
| upuai version | Exibir a versão do CLI, hash do commit e data de build. |
| upuai completion [bash|zsh|fish|powershell] | Gerar scripts de autocompletion para seu shell. |
| upuai upgrade | Atualizar o CLI para a versão mais recente. Baixa o binário do GitHub Releases. |
$ upuai version
upuai-cli/1.2.0 (abc1234) built 2026-02-14$ upuai completion zsh > ~/.zsh/completions/_upuai
✓ Completion script generated$ upuai upgrade
▸ Checking for updates...
✓ Upgraded from 1.1.0 → 1.2.0Flags Globais
Estas flags estão disponíveis em todos os comandos e sobrescrevem os padrões do contexto.
| Flag | Curta | Tipo | Padrão | Descrição |
|---|---|---|---|---|
| --project | -p | string | — | Especificar um projeto pelo ID ou nome. Sobrescreve o projeto vinculado. |
| --environment | -e | string | — | Especificar o ambiente (production, staging, development). |
| --output | -o | "json" | "table" | "text" | table | Formato de saída. Use json para scripts e pipelines CI/CD. |
| --yes | -y | boolean | false | Pular todos os prompts de confirmação. Útil para CI/CD. |
| --verbose | -v | boolean | false | Ativar saída detalhada incluindo requisições API e tempo. |
| --help | -h | boolean | — | Exibir ajuda para qualquer comando. |
| --version | — | boolean | — | Exibir a versão do CLI. |
$ upuai deploy --project my-app --environment staging --output json --yes
{
"status": "success",
"deployId": "dep_abc123",
"url": "https://my-app-staging.upuai.com.br"
}