UpuaiUpuai
Referência CLI

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.

O CLI respeita as configurações do .upuai/config.json quando presente. Flags do CLI sobrescrevem tanto a configuração local quanto as configurações do dashboard.

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)

Terminal
$ brew tap saiph-ti/upuai-cli
$ brew install upuai

Scoop (Windows)

PowerShell
> scoop bucket add upuai https://github.com/saiph-ti/scoop-upuai-cli
> scoop install upuai

Direct download (Linux / macOS)

Terminal
$ 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/
Terminal
$ upuai version
upuai/0.0.2 (206c727) built 2026-04-23T18:37:12Z

Autenticação

Autentique-se no Upuai Cloud para acessar seus projetos e recursos.

ComandoDescrição
upuai loginAutenticar via navegador. Abre uma janela do navegador para login OAuth e armazena as credenciais localmente.
upuai logoutLimpar credenciais armazenadas e revogar a sessão atual.
upuai whoamiExibir o usuário autenticado, organização e projeto padrão.
Terminal
$ upuai login

▸ Opening browser for authentication...
✓ Logged in as gabriel@upuai.com.br
  Organization: Upuai Labs
  Default project: my-app
Terminal
$ upuai whoami

User: gabriel@upuai.com.br
Organization: Upuai Labs
Default project: my-app
Auth é sempre via `upuai login` interativo (browser OAuth ou email OTP) — mesmo padrão de `railway login` / `vercel login` / `fly auth login`. Após login, credenciais persistem em `~/.upuai/credentials.json` e o JWT auto-refresha.

Gerenciamento de Projetos

Inicialize novos projetos, vincule diretórios e gerencie seus projetos no Upuai Cloud.

ComandoAliasDescrição
upuai initInicializar um novo projeto no diretório atual. Auto-detecta o framework e cria uma configuração local com as definições do projeto.
upuai linkVincular o diretório atual a um projeto existente no Upuai Cloud. Seletor interativo permite escolher entre seus projetos.
upuai unlinkDesvincular o diretório atual do projeto. Remove o arquivo local .upuai/config.json.
upuai listupuai lsListar todos os seus projetos com nome, ID, status e data de criação.
upuai openAbrir o projeto vinculado no navegador. Navega diretamente para o dashboard do projeto.
upuai deleteDeletar o projeto vinculado. Esta ação é irreversível e requer dupla confirmação (re-digitação do nome).
upuai statusExibir o status do projeto incluindo serviços, URLs, estado do deploy e uso de recursos.
Terminal
$ upuai init

? Project name: my-app
? Detected: Node.js (Next.js)
? Build command: pnpm run build
? Start command: pnpm start

✓ Project ready to deploy
Terminal
$ upuai link

? Select a project:
  ❯ my-app (production)
    api-service (staging)
    landing-page (production)

✓ Linked to my-app
Terminal
$ 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
Terminal
$ 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.br

Deploy

Faça deploy da sua aplicação no Upuai Cloud. Suporta deploy zero-config, watch mode, rollbacks, redeploys e promoção entre ambientes.

ComandoAliasDescrição
upuai deployupuai upFazer deploy do diretório atual no Upuai Cloud. Auto-detecta linguagem, framework e configurações de build.
upuai deploy --watchIniciar watch mode. Faz redeploy automaticamente quando arquivos mudam (debounce de 500ms).
upuai redeployRefazer o deploy do último deployment. Reconstrói e reinicia com a mesma configuração.
upuai rollbackReverter para o deploy anterior bem-sucedido. Troca instantânea sem downtime.
upuai promotePromover o deploy atual de staging para produção.
upuai downRemover o último deployment e parar o serviço. Requer confirmação.
FlagCurtaTipoPadrãoDescrição
--watch-wbooleanfalseAtivar watch mode para redeploy automático ao mudar arquivos.
Terminal
$ 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
Terminal
$ upuai deploy --watch

◉ Watching for changes...
▸ src/index.ts changed — redeploying...
✓ Deployed in 38s
◉ Watching for changes...
Terminal
$ upuai rollback

✓ Rolled back to previous deployment (dep_xyz789)
Terminal
$ upuai promote

▸ Promoting staging → production
▸ Deployment dep_stg_001 → dep_prd_002
✓ Production updated. URL: https://my-app.upuai.com.br
Terminal
$ 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.

ComandoDescrição
upuai addAdicionar um novo serviço ao projeto via wizard interativo. Suporta tipos app, database, Redis, function, bucket, volume e Docker.
upuai psListar os processos do serviço vinculado (web/worker/clock/release) declarados via Procfile ou upuai.toml [processes.*], com tipo, réplicas e comando.
upuai restartReiniciar o serviço vinculado. Requer confirmação (pule com --yes). Use --process <nome> para reiniciar um único processo de um app multi-processo.
upuai logsVisualizar 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 shellAbrir um subshell interativo com as variáveis do serviço injetadas (paridade com `railway shell`). Detecta $SHELL no Unix e %COMSPEC% no Windows.
FlagCurtaTipoPadrãoDescrição
--lines-ninteger100Número de linhas de log a buscar (para upuai logs).
--service-sstringNome, slug ou ID do serviço (sobrescreve o serviço vinculado). Disponível em `run`, `shell` e `variables`.
--processstringMira um único processo de um serviço multi-processo (Procfile). Disponível em `logs`, `restart` e `ssh`. Liste com `upuai ps`.
--shellstringCaminho do binário do shell (default: $SHELL ou cmd.exe). Apenas em `shell`.
Terminal
$ upuai add

? Service type:
  ❯ App
    Database (PostgreSQL, MySQL, MongoDB)
    Redis
    Function
    Bucket
    Volume
    Docker

? Service name: api
✓ Service api added to project
Terminal
$ 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
Terminal
$ 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
Terminal
$ 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
Terminal
$ upuai restart

▸ Restarting web...
✓ Service restarted
Terminal
$ upuai run npx prisma migrate deploy

▸ Injecting 5 environment variable(s)
▸ Running: npx prisma migrate deploy

Applying migration: 20260214_add_orders
✓ Migration complete
Terminal
$ upuai run -s api -- env | grep DATABASE_URL
DATABASE_URL=postgres://user:****@cmocv2dv6001i01o2ul89crrc.db.upuai.cloud:5432/app
Terminal
$ 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 %  exit

Banco 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.

ComandoDescrição
upuai db connectAbrir uma sessão psql interativa contra o banco vinculado via endpoint público. Requer psql instalado localmente (postgresql-client / libpq).
upuai db connect --printImprimir a connection string pública (URI completo + host/porta) sem abrir o psql. Útil para scripts.
upuai db backup --out file.dumpRodar pg_dump contra o endpoint público e salvar em formato custom no arquivo informado. Requer pg_dump local.
upuai db restore -f file.dumpRestaurar um .dump via pg_restore. Por padrão usa --clean --if-exists --no-owner --no-acl. Requer confirmação (pule com --yes).
FlagCurtaTipoPadrãoDescrição
--outstringArquivo de saída do pg_dump (obrigatório em `db backup`).
--file-fstringArquivo .dump de entrada (obrigatório em `db restore`).
--printbooleanfalseEm `db connect`, imprime a connection string e sai sem abrir o psql.
--enablebooleanfalseHabilita o endpoint público sem prompt se ainda estiver desabilitado.
Terminal
$ 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
Terminal
$ upuai db connect --print

Host: cmocv2dv6001i01o2ul89crrc.db.upuai.cloud  Port: 5432

postgres://app_user:****@cmocv2dv6001i01o2ul89crrc.db.upuai.cloud:5432/app?sslmode=require
Terminal
$ 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)
Terminal
$ 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 complete

Ambientes

Gerencie ambientes do projeto. O comando environment suporta troca interativa e subcomandos para controle completo.

ComandoAliasDescrição
upuai environmentupuai envTrocar o ambiente ativo interativamente usando um menu de seleção.
upuai env listListar 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).
Terminal
$ upuai env

? Select environment:
  ❯ production (active)
    staging
    development

✓ Active environment: production
Terminal
$ upuai env list

NAME           ID              ACTIVE   EPHEMERAL
production     env_abc123      ●        No
staging        env_def456                No
development    env_ghi789                No
Terminal
$ upuai env switch staging
✓ Active environment: staging
Terminal
$ upuai env new preview
✓ Environment preview created

Configuração

Gerencie variáveis de ambiente e domínios customizados para seus serviços.

ComandoAliasDescrição
upuai variables listupuai vars listListar todas as variáveis de ambiente. Valores secretos são mascarados.
upuai variables set KEY=VALUEDefinir 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 listupuai domains listListar 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).
Terminal
$ upuai vars set DATABASE_URL=postgres://user:pass@host/db NODE_ENV=production
✓ 2 variables set
Terminal
$ upuai vars list

NAME              VALUE                    SECRET
DATABASE_URL      postgres://user:***      Yes
REDIS_URL         redis://localhost:6379   No
API_KEY           ****                     Yes
NODE_ENV          production               No
Terminal
$ 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.
Terminal
$ 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_ghi789
Variáveis são isoladas por ambiente e por serviço. Use --environment para escolher o ambiente e --service (ou -s) para mirar um serviço diferente do vinculado — paridade com `railway variable list -s Postgres`.

Utilitários

Comandos utilitários para gerenciar o próprio CLI.

ComandoDescrição
upuai versionExibir 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 upgradeAtualizar o CLI para a versão mais recente. Baixa o binário do GitHub Releases.
Terminal
$ upuai version
upuai-cli/1.2.0 (abc1234) built 2026-02-14
Terminal
$ upuai completion zsh > ~/.zsh/completions/_upuai
✓ Completion script generated
Terminal
$ upuai upgrade
▸ Checking for updates...
✓ Upgraded from 1.1.0 → 1.2.0

Flags Globais

Estas flags estão disponíveis em todos os comandos e sobrescrevem os padrões do contexto.

FlagCurtaTipoPadrãoDescrição
--project-pstringEspecificar um projeto pelo ID ou nome. Sobrescreve o projeto vinculado.
--environment-estringEspecificar o ambiente (production, staging, development).
--output-o"json" | "table" | "text"tableFormato de saída. Use json para scripts e pipelines CI/CD.
--yes-ybooleanfalsePular todos os prompts de confirmação. Útil para CI/CD.
--verbose-vbooleanfalseAtivar saída detalhada incluindo requisições API e tempo.
--help-hbooleanExibir ajuda para qualquer comando.
--versionbooleanExibir a versão do CLI.
Terminal
$ upuai deploy --project my-app --environment staging --output json --yes

{
  "status": "success",
  "deployId": "dep_abc123",
  "url": "https://my-app-staging.upuai.com.br"
}
Para execução não-interativa de comandos (após login), use `--yes` com flags explícitas para pular wizards. Auth headless sem login interativo não é suportada hoje.