Docs/ CLI/ Referência de Comandos

Referência de Comandos

Os 48 comandos da versão publicada (v1.10.2), agrupados por tarefa. Cada bloco abaixo é o <code>--help</code> do comando reduzido à sintaxe: o que você lê aqui é o que o binário aceita.

Configuração e opções globais

A maioria dos comandos conversa com um servidor sh0 pela API. Eles o encontram nesta ordem:

  • As variáveis de ambiente SH0_API_URL e SH0_API_TOKEN, quando as duas estão definidas -- o caminho para CI. Elas têm prioridade sobre o arquivo.
  • O arquivo ~/.sh0/config.toml, gravado por sh0 login. sh0 config show mostra o servidor e um token mascarado; sem nenhum dos dois, os comandos param com “No configuration found. Run `sh0 login` or set SH0_API_URL and SH0_API_TOKEN environment variables.”
  • As opções globais são apenas --log-level, -h, --help e -V, --version. --config aponta para o arquivo de configuração do servidor (/etc/sh0/config.toml) e só interessa aos comandos que rodam no servidor, como sh0 serve.
  • --json é uma opção de cada comando: existe onde a referência abaixo a mostra (listagens, cron runs…), não em todos.
Terminal
$ sh0 whoami
  Server:  https://panel.example.com
  User:    [email protected]
  Role:    owner

$ SH0_API_URL=https://panel.example.com SH0_API_TOKEN=sh0_... sh0 apps
  NAME      STATUS    BRANCH  PORT  REPLICAS  UPDATED
  --------  --------  ------  ----  --------  -------
  my-api    running   main    3001  1         2m ago
Warning
Não existe nenhuma opção global --url, --token, --json ou --verbose. Um script escrito com base numa versão anterior desta página que as usava falha com “unexpected argument”: use as variáveis de ambiente acima.

Como ler os blocos: <APP> é obrigatório, [--opção] é opcional, ... se repete. A linha que começa com # é a descrição do próprio comando. <APP> aceita o nome ou o ID de uma aplicação; a maioria dos comandos de serviços (sh0 db…) recebe um ID, exibido na criação do recurso e pelo respectivo list.

Conta e configuração da CLI

Conectar a CLI a um servidor e verificar quem você é nele.

sh0 login

sh0 login --help
# Authenticate with a sh0 server
sh0 login [--url <URL>]

sh0 whoami

sh0 whoami --help
# Show current user and server info
sh0 whoami

sh0 config

sh0 config --help
# Show current configuration
sh0 config show
# Get a specific configuration value
sh0 config get <KEY>
# Set a configuration value
sh0 config set <KEY> <VALUE>

sh0 version

sh0 version --help
# Print version information
sh0 version

Diretório de trabalho

Vincular um diretório local a uma aplicação, verificá-lo antes do deploy e refazer o deploy a cada alteração.

sh0 init

sh0 init --help
# Initialize a project directory for sh0 deployments
sh0 init [PATH]

sh0 link

sh0 link --help
# Link the current directory to an existing app on the server
sh0 link <APP> [--path <PATH>]

sh0 open

sh0 open --help
# Open the app's primary domain in the default browser
sh0 open [APP]

sh0 watch

sh0 watch --help
# Watch for file changes and auto-push
sh0 watch [PATH] [--name <NAME>] [--project <PROJECT>] [--port <PORT>] [--no-check] [--timeout <TIMEOUT>] [--debounce <DEBOUNCE>]

sh0 check

sh0 check --help
# Run Code Health Check on local directory
sh0 check [PATH] [--json]

Deploy

sh0 push envia um diretório como arquivo compactado e cria ou atualiza a aplicação: é o caminho principal, sem repositório Git. Veja Deploy com push.

sh0 push

sh0 push --help
# Push local directory to deploy (create or update)
sh0 push [PATH] [--name <NAME>] [--project <PROJECT>] [--port <PORT>] [--no-check] [--timeout <TIMEOUT>]

sh0 deploy

sh0 deploy --help
# Trigger a deployment
sh0 deploy <APP> [--message <MESSAGE>] [--wait]

sh0 templates

sh0 templates --help
# List available templates
sh0 templates list
# Show template details
sh0 templates info <NAME>
# Deploy a template
sh0 templates deploy --app-name <APP_NAME> <NAME> [--var]

sh0 compose

sh0 compose --help
# Deploy a Docker Compose file
sh0 compose deploy --app-name <APP_NAME> [PATH] [--var] [--wait]
# Validate a Docker Compose file without deploying
sh0 compose validate [PATH]

sh0 yaml

sh0 yaml --help
# Apply a sh0.yaml configuration
sh0 yaml apply [PATH]
# Validate a sh0.yaml configuration without applying
sh0 yaml validate [PATH]
# Export current configuration as sh0.yaml
sh0 yaml export [--project <PROJECT>]

sh0 export

sh0 export --help
# Export app configuration to a platform-specific format
sh0 export <APP> <FORMAT> [--output <OUTPUT>]

Gerenciar aplicações

Ciclo de vida, variáveis, domínios, logs e um shell numa aplicação em execução. As variáveis são aplicadas no próximo deploy.

sh0 apps

sh0 apps --help
# List all applications
sh0 apps [--json]

sh0 status

sh0 status --help
# Show server or app status
sh0 status [APP] [--json]

sh0 restart

sh0 restart --help
# Restart an application
sh0 restart <APP>
Warning
Numa aplicação que demora a parar, sh0 restart pode terminar com “operation timed out” após 30 segundos enquanto o reinício continua e é concluído no servidor (medido: 41 s até a resposta da API). Verifique com sh0 status <APP> antes de tentar de novo.

sh0 stop

sh0 stop --help
# Stop an application
sh0 stop <APP> [--yes]

sh0 start

sh0 start --help
# Start a stopped application
sh0 start <APP>

sh0 delete

sh0 delete --help
# Delete an application and its resources
sh0 delete <APP> [--yes]

sh0 scale

sh0 scale --help
# Scale application replicas
sh0 scale <APP> [REPLICAS] [--auto] [--status] [--json]

sh0 env

sh0 env --help
# List environment variables
sh0 env <APP> list [--reveal]
# Set an environment variable
sh0 env <APP> set <PAIR> [--build]
# Delete an environment variable
sh0 env <APP> delete <KEY>
Terminal
$ sh0 env my-api set "DATABASE_URL=postgresql://appuser:<password>@my-pg.internal:5432/appdb"
[ok] Set DATABASE_URL for 'my-api'

$ sh0 env my-api list
  KEY           VALUE    BUILD  CREATED
  ------------  -------  -----  -------
  DATABASE_URL  *******  no     4m ago
  GREETING      *******  no     16m ago

sh0 domains

sh0 domains --help
# List domains for the app
sh0 domains <APP> list
# Add a domain to the app
sh0 domains <APP> add <DOMAIN> [--primary]
# Remove a domain from the app
sh0 domains <APP> remove <DOMAIN> [--yes]

sh0 logs

sh0 logs --help
# Stream application logs
sh0 logs <APP> [--follow] [--tail <TAIL>]

sh0 ssh

sh0 ssh --help
# Execute command in app container
sh0 ssh <APP> [COMMAND]...
Note
sh0 ssh precisa de um terminal interativo (a partir de um script sem terminal ele para com “cannot attach stdin to a TTY-enabled container”). Coloque -- antes de um comando que tem as próprias opções: sh0 ssh my-api -- node --version.

Tarefas agendadas, hooks e pré-visualizações

Antes de criar uma tarefa agendada, leia onde o comando é executado: ele não vê as variáveis da sua aplicação.

sh0 cron

sh0 cron --help
# List cron jobs
sh0 cron list [--app <APP>] [--json]
# Create a new cron job
sh0 cron create --app <APP> --name <NAME> --schedule <SCHEDULE> --command <COMMAND> [--image <IMAGE>] [--timeout <TIMEOUT>]
# Manually trigger a cron job
sh0 cron trigger <ID>
# Show execution history for a cron job
sh0 cron runs <ID> [--json]
# Delete a cron job
sh0 cron delete <ID> [--yes]

sh0 hooks

sh0 hooks --help
# List deploy hooks for an app
sh0 hooks <APP> list [--json]
# Create a deploy hook
sh0 hooks <APP> create --hook-type <type> --command <COMMAND> [--timeout <TIMEOUT>]
# Delete a deploy hook
sh0 hooks <APP> delete <ID>

sh0 preview

sh0 preview --help
# List preview environments for an app
sh0 preview <APP> list [--json]
# Destroy a preview environment
sh0 preview <APP> delete <ID>
# Enable preview environments for an app
sh0 preview <APP> enable [--ttl <TTL>]
# Disable preview environments for an app
sh0 preview <APP> disable

Serviços

Servidores de banco de dados, autenticação, tempo real, funções, e-mail, armazenamento e disponibilidade. Cada comando tem um alias curto (db, auth, realtime, fn, storage); o nome longo também funciona.

sh0 db

sh0 db --help
# List all database servers
sh0 db list [--json]
# Show database server details
sh0 db info <ID> [--json]
# Create a new database server
sh0 db create --name <NAME> --engine <ENGINE> [--project <PROJECT>]
# Update a database server
sh0 db update <ID> [--name <NAME>] [--project <PROJECT>]
# Delete a database server
sh0 db delete <ID> [--yes]
# Start a database server
sh0 db start <ID>
# Stop a database server
sh0 db stop <ID>
# Recreate a database server container
sh0 db recreate <ID>
# Show connection info for a database server
sh0 db connection-info <ID> [--json]
# Create a database on a server
sh0 db create-database --name <NAME> <ID>
# Create a user on a database server
sh0 db create-user --username <USERNAME> --password <PASSWORD> <ID>
# Grant a user access to a database
sh0 db grant --user <USER> --database <DATABASE> <ID> [--privileges <PRIVILEGES>]
# Enable PostgREST sidecar
sh0 db enable-postgrest <ID> [--anon-role <ANON_ROLE>] [--schemas <SCHEMAS>]
# Disable PostgREST sidecar
sh0 db disable-postgrest <ID>

sh0 auth

sh0 auth --help
# List all auth servers
sh0 auth-servers list [--json]
# Show auth server details
sh0 auth-servers info <ID> [--json]
# Create a new auth server
sh0 auth-servers create --name <NAME> --database-server <DATABASE_SERVER> [--project <PROJECT>]
# Delete an auth server
sh0 auth-servers delete <ID> [--yes]
# Start an auth server
sh0 auth-servers start <ID>
# Stop an auth server
sh0 auth-servers stop <ID>

sh0 realtime

sh0 realtime --help
# List all realtime servers
sh0 realtime-servers list [--json]
# Show realtime server details
sh0 realtime-servers info <ID> [--json]
# Create a new realtime server
sh0 realtime-servers create --name <NAME> [--project <PROJECT>]
# Delete a realtime server
sh0 realtime-servers delete <ID> [--yes]
# Start a realtime server
sh0 realtime-servers start <ID>
# Stop a realtime server
sh0 realtime-servers stop <ID>

sh0 fn

sh0 fn --help
# List all function servers
sh0 function-servers list [--json]
# Show function server details
sh0 function-servers info <ID> [--json]
# Create a new function server
sh0 function-servers create --name <NAME> [--project <PROJECT>]
# Delete a function server
sh0 function-servers delete <ID> [--yes]
# Start a function server
sh0 function-servers start <ID>
# Stop a function server
sh0 function-servers stop <ID>

sh0 mail

sh0 mail --help
# List all mail domains
sh0 mail list [--json]
# Show mail domain details
sh0 mail info <ID> [--json]
# Create a new mail domain
sh0 mail create --domain <DOMAIN> [--project <PROJECT>]
# Delete a mail domain
sh0 mail delete <ID> [--yes]
# Start a mail domain
sh0 mail start <ID>
# Stop a mail domain
sh0 mail stop <ID>
# Check DNS records for a mail domain
sh0 mail dns-check <ID> [--json]
# Create a mailbox on a mail domain
sh0 mail create-mailbox --email <EMAIL> --password <PASSWORD> <ID> [--display-name <DISPLAY_NAME>]
# Create an email alias on a mail domain
sh0 mail create-alias --source <SOURCE> --destination <DESTINATION> <ID>

sh0 storage

sh0 storage --help
# List all file storage instances
sh0 file-storage list [--json]
# Show file storage instance details
sh0 file-storage info <ID> [--json]
# Create a new file storage instance
sh0 file-storage create --name <NAME> [--project <PROJECT>]
# Delete a file storage instance
sh0 file-storage delete <ID> [--yes]
# Start a file storage instance
sh0 file-storage start <ID>
# Stop a file storage instance
sh0 file-storage stop <ID>
# Create a bucket in a storage instance
sh0 file-storage create-bucket --name <NAME> <ID>
# Create an access key for a storage instance
sh0 file-storage create-key <ID> [--json]
# Show storage usage statistics
sh0 file-storage usage <ID> [--json]

sh0 uptime

sh0 uptime --help
# List uptime checks
sh0 uptime list [--app <APP>] [--json]
# Show uptime check details
sh0 uptime info <ID> [--json]
# Create a new uptime check
sh0 uptime create --app <APP> --url <URL> [--interval <INTERVAL>] [--method <METHOD>] [--timeout <TIMEOUT>] [--expected-status <EXPECTED_STATUS>] [--failure-threshold <FAILURE_THRESHOLD>]
# Delete an uptime check
sh0 uptime delete <ID> [--yes]
# List uptime incidents for a check
sh0 uptime incidents <CHECK_ID> [--json]

Servidores e painel

Os nós remotos e o domínio do próprio painel.

sh0 nodes

sh0 nodes --help
# List all server nodes
sh0 nodes list [--json]
# Show node details
sh0 nodes info <ID> [--json]
# Register a new server node
sh0 nodes create --name <NAME> --host <HOST> --ssh-user <SSH_USER> [--ssh-key <SSH_KEY>] [--password <PASSWORD>] [--port <PORT>]
# Remove a node from the cluster
sh0 nodes delete <ID> [--yes]
# Test SSH and Docker connectivity to a node
sh0 nodes test <ID> [--json]

sh0 panel-domain

sh0 panel-domain --help
# Domaine du panneau d'administration : le lire, le poser, le retirer.
sh0 panel-domain [COMMAND] [--data-dir <DATA_DIR>] [--db <DB>] [--caddy-data <CADDY_DATA>] [--jwt-secret-path <JWT_SECRET_PATH>] [--port <PORT>]
# Poser le domaine et attendre l'émission du certificat
sh0 panel-domain set <DOMAIN> [--no-wait]
# Retirer la route et le réglage
sh0 panel-domain clear

Administração do servidor

Estes comandos rodam no servidor, como root, e agem sobre a instalação local em vez de passar pela API. Alguns imprimem a ajuda em francês na versão atual.

sh0 serve

sh0 serve --help
# Start the sh0 server
sh0 serve [OPTIONS]    # sh0 serve --help lists every option

sh0 setup

sh0 setup --help
# Run initial setup wizard
sh0 setup

sh0 install-dns-caddy

sh0 install-dns-caddy --help
# Install a Caddy that can answer the DNS-01 ACME challenge (ISSUE-158).
sh0 install-dns-caddy

sh0 users

sh0 users --help
# List all users (reads the local database when run on the server box, the API otherwise)
sh0 users list [--json] [--data-dir <DATA_DIR>] [--db <DB>]
# Invite a new user
sh0 users invite <EMAIL> [--password <PASSWORD>] [--role <ROLE>] [--display-name <DISPLAY_NAME>]
# Update a user
sh0 users update <ID> [--role <ROLE>] [--display-name <DISPLAY_NAME>]
# Remove a user
sh0 users remove <ID> [--yes]
# Reset a user's password locally (recovery path; run on the server box, no login required)
sh0 users reset-password <EMAIL> [--password <PASSWORD>] [--disable-2fa] [--data-dir <DATA_DIR>] [--db <DB>]

sh0 projects

sh0 projects --help
# List all projects
sh0 projects list [--json]
# Create a new project
sh0 projects create <NAME> [--description <DESCRIPTION>] [--color <COLOR>]
# Delete an empty project (refused while it still holds apps, databases or services)
sh0 projects delete <PROJECT> [--yes]
# List project members
sh0 projects members <PROJECT> [--json]
# Add a member to a project
sh0 projects add-member <PROJECT> <USER> [--role <ROLE>]
# Remove a member from a project
sh0 projects remove-member <PROJECT> <USER>

sh0 update

sh0 update --help
# Update sh0, or roll back to the previous version
sh0 update [--rollback] [--channel <CHANNEL>] [--force] [--yes]

sh0 doctor

sh0 doctor --help
# Préflight d'hôte : Docker, ports, disque, certificats, horloge.
sh0 doctor [COMMAND] [--json] [--db <DB>] [--data-dir <DATA_DIR>] [--caddy-data <CADDY_DATA>] [--port <PORT>]
# Count restore rows that migration 055 could not reach (ISSUE-086).
sh0 doctor backup-rows [--json] [--db <DB>]
# List host mounts that the bind whitelist would refuse today (ISSUE-176).
sh0 doctor bind-mounts [--json] [--db <DB>] [--all]

sh0 instance

sh0 instance --help
# Écrire un instantané de cette instance dans un fichier
sh0 instance backup [--data-dir <DATA_DIR>] [--out <OUT>] [--encrypt]
# Reposer une instance sauvegardée sur cette machine
sh0 instance restore --file <FILE> [--data-dir <DATA_DIR>] [--dry-run] [--force]
# Remplacer la clé maîtresse et rechiffrer tous les secrets de la base
sh0 instance rotate-key [--data-dir <DATA_DIR>] [--dry-run] [--yes] [--backup-out <BACKUP_OUT>]

sh0 uninstall

sh0 uninstall --help
# Uninstall sh0 (remove binary and optionally data)
sh0 uninstall [--purge]

sh0 destroy

sh0 destroy --help
# Destroy everything: stop and remove all containers, images, volumes, networks, data, and binary
sh0 destroy
Anterior
Deploy por push
Próximo
Autenticação da API