CLI

Faça deploy, acompanhe logs, rode comandos e gerencie suas aplicações direto do terminal.

O railyard é um único binário em Go que conversa com a API REST do Railyard: faça deploy, acompanhe logs, rode comandos, gerencie variáveis de ambiente, domínios, bancos de dados e servidores direto do terminal. Não precisa de nenhum runtime instalado.

Instalação

Um binário só, sem dependências, para macOS e Linux em arm64 e amd64. Nada é fixo no código — a CLI conversa com qualquer instalação do Railyard em que você estiver logado.

brew install almokhtarbr/railyard/railyard           # Homebrew
curl -fsSL https://app.railyard.run/install.sh | sh   # instalador em uma linha (verifica o sha256)

Depois, em vez de brew upgrade:

railyard upgrade   # troca este binário pelo build mais recente que seu Railyard oferece
railyard version   # mostra o build instalado

railyard login

Confirm code ABCD2345 in your browser: https://app.railyard.run/cli/auth/ABCD2345
Logged in to https://app.railyard.run

Esse é o fluxo de dispositivo (a mesma ideia do gh auth login ou do fly auth login): a CLI abre essa URL no seu navegador, você digita o código mostrado no terminal dentro do painel onde já está logado, e a CLI recebe um token gerado para você — sem nunca digitar senha ou token no terminal. Por padrão ela faz login em app.railyard.run; defina RAILYARD_API para apontar para outro lugar.

Seus tokens de API, chaves SSH, contas de nuvem e provedores de Git ficam todos em uma única página do painel: Configurações → Acesso e tokens (app.railyard.run/access).

railyard whoami    # equipe, scope do token, limites (alias: me)
railyard logout    # esquece o token salvo

Configuração e CI

O token e a URL da API ficam salvos em ~/.railyard/config.json (modo 0600). Para CI ou containers, pule o login e defina variáveis de ambiente em vez disso — elas sempre têm prioridade sobre o arquivo:

Variável	Sobrescreve
`RAILYARD_API` (ou `RAILYARD_API_URL`)	a URL do control plane
`RAILYARD_TOKEN`	o bearer token
`RAILYARD_CONFIG`	o caminho do arquivo de configuração (padrão `~/.railyard/config.json`)

--json em qualquer comando imprime a resposta bruta da API em vez de uma tabela.

Vincular uma aplicação a um diretório

cd my-app && railyard link my-app   # escreve ./.railyard.json: {"app": "my-app"}
railyard deploy --follow            # o argumento app agora é opcional neste diretório
railyard unlink

Comandos que aceitam [app] usam a aplicação vinculada, encontrada subindo do diretório atual até o primeiro .railyard.json. Em qualquer outro lugar, <app> é um id ou um nome (um prefixo sem ambiguidade também funciona).

Autocompletar do shell

railyard completion zsh  > "${fpath[1]}/_railyard"
railyard completion bash > /etc/bash_completion.d/railyard
railyard completion fish > ~/.config/fish/completions/railyard.fish

Aplicações

railyard apps
railyard app [app]
railyard open [app]
railyard create <name> <git-url> [flags]
railyard templates [--verified]
railyard launch <template> [--server id]
railyard clone [app]
railyard promote [app]

apps — id · nome · status do último deploy · url, um por linha.
app — JSON completo de uma aplicação.
open — imprime e abre a URL da aplicação no seu navegador.
flags de create: --server <id|hostname>, --ref <branch>, --port <n> (detectada do repositório se omitida), --addons postgres,redis,…, --db-extensions <ext,…>.
templates — o catálogo de um clique; launch faz o deploy de um agora.
clone — copia a aplicação para uma cópia de staging; promote leva a release de uma cópia de staging para produção (como os pipelines do Heroku).

railyard create my-app https://github.com/me/my-app --ref main --port 3000
railyard clone my-app && railyard promote my-app-staging

Deploys

railyard deploy [app] [flags]
railyard deploys [--app <app>] [--status <s>]
railyard deploy:logs <id> [--follow]
railyard deploy:approve|reject|cancel <deploy-id>
railyard releases [app]
railyard rollback <app> <version> [--code-only] [--message "note"]
railyard deploy-window <app> off | <mon,tue,...> <09:00> <17:00> [zone]

Flags de deploy: --ref <branch|tag|sha> faz deploy dessa ref uma única vez, sem mudar a branch acompanhada; --message "note"; --follow transmite o log do build e do release; --force pula as verificações do primeiro deploy; --at <ISO 8601> agenda o deploy (cancele com deploy:cancel); --anyway faz deploy fora da janela de deploy.

deploy --local builda o diretório atual com o seu próprio Docker, em vez do builder da equipe, sobe a imagem e faz o deploy dela uma única vez — como fly deploy --local-only:

railyard deploy [app] --local [--image repo[:tag]]

--image envia para o seu próprio registro (seu docker login), em vez do registro de build da equipe; um repositório sem tag recebe :local-<UTC timestamp>.

deploy-window — pushes e deploys automáticos fora da janela esperam até ela abrir; deploy --anyway ignora isso. rollback refaz o deploy do commit de uma release anterior e restaura as variáveis de ambiente dela (--code-only mantém as de hoje).

railyard deploy --ref v1.4.2 --message "hotfix" --follow
railyard rollback my-app 112 --message "bad migration"
railyard deploy-window my-app mon,tue,wed,thu,fri 09:00 17:00 America/New_York

Deploy por Git

railyard git:remote [app] [--remote name]
railyard git:strict <app> on|off

git:remote adiciona um remote git chamado railyard apontando para essa aplicação, e um credential helper de git que responde com seu token, então git push railyard main faz o deploy daquele commit exato e transmite o log do build de volta. git:strict (ativado por padrão) rejeita um push cujo build falha, então a branch continua no commit antigo; off aceita o push primeiro e faz o deploy depois.

cd my-app && railyard git:remote
git push railyard main

Cada push tem um limite de 1 GB. Os repositórios enviados por push também contam dentro de uma cota por equipe (5 GB por padrão); passar do limite rejeita o push mostrando o uso e sugerindo excluir aplicações para as quais você não envia push mais. O Railyard roda git gc nos repositórios enviados por push todas as noites para mantê-los pequenos.

Runtime

railyard logs [app] [--follow] [--process web] [--tail 200]
railyard logs:search <app> <text|/regex/> [--level error] [--range 24h] [--process web]
railyard ps [app]
railyard restart [app] [--process web]
railyard run <app> [--process worker] [--exec] -- <command...>
railyard scale <app> <process>=<n> …
railyard wake [app]
railyard sleep <app> <10|30|60|360|1440|off>

run inicia um container novo e descartável a partir da release atual (como heroku run), ou executa dentro do container que já está rodando com --exec; ele transmite a saída e termina com o mesmo código de saída do comando remoto. sleep para os containers da aplicação depois desses minutos de inatividade, e wake, ou a próxima requisição, os traz de volta; off desativa isso.

railyard logs my-app --follow --process web
railyard run my-app -- bin/rails db:migrate
railyard scale my-app web=2 worker=1
railyard sleep my-app 30

Variáveis de configuração e domínios

railyard env [app] [--reveal[=KEY]]
railyard env:set <app> KEY=VALUE …
railyard env:unset <app> KEY
railyard configs
railyard domains [app]
railyard domain:add <app> <hostname> [--redirect]
railyard domain:rm <app> <domain-id>

env oculta os valores, a menos que você use --reveal (todos) ou --reveal KEY (um só). configs lista as entradas de configuração de toda a equipe (somente leitura pela CLI).

railyard env my-app --reveal SECRET_KEY_BASE
railyard env:set my-app RAILS_ENV=production LOG_LEVEL=info
railyard domain:add my-app www.example.com --redirect

Banco de dados e volumes

railyard db:query <app> "<sql>" [--write]
railyard db:backups [app]
railyard db:backup [app]
railyard db:restore <backup-id>
railyard db:url <backup-id>
railyard volumes [app]
railyard volume:backup <app> <volume-name>
railyard volume:restore <backup-id>

db:query é somente leitura, a menos que você use --write (precisa de um token com escopo de escrita). db:url retorna um link de download assinado para um backup.

railyard db:query my-app "select count(*) from users"
railyard db:backup my-app
railyard volume:backup my-app data

Manifest

railyard manifest:pull [app] [--secrets] [--out railyard.yml]
railyard manifest:apply [app] <file.yml>
railyard manifest:validate [file.yml]

manifest:pull imprime a aplicação como um railyard.yml (--secrets inclui os valores das variáveis); manifest:apply aplica um arquivo à aplicação. manifest:validate verifica um arquivo local (./railyard.yml se omitido) sem aplicá-lo nem precisar de nenhuma aplicação — chaves desconhecidas recebem uma sugestão (contaner_port → “did you mean container_port?”); termina com 0 e imprime “is valid” se não há problemas, ou termina com 1 e os lista.

railyard manifest:pull my-app --out railyard.yml
railyard manifest:apply my-app railyard.yml
railyard manifest:validate railyard.yml

Observabilidade

railyard metrics [app] [--range 1h|24h|7d|30d]
railyard autoscale <app> --max N [--min N] [--p95 ms] [--cpu %]
railyard autoscale <app> off

metrics imprime requisições, p95, taxa de erro e os endpoints mais lentos. autoscale escala as réplicas web entre --min/--max quando a latência p95 ou a CPU passa dos limites informados; off remove os limites.

railyard metrics my-app --range 7d
railyard autoscale my-app --max 5 --min 1 --p95 300 --cpu 80

Notificações e webhooks

railyard notify
railyard webhooks

Listas, para toda a equipe, das regras de notificação e dos endpoints de webhook (somente leitura pela CLI; crie e edite pelo painel).

Servidores

railyard servers
railyard server <id>
railyard server:cordon <server-id>
railyard server:uncordon <server-id>
railyard server:reboot <server-id>
railyard server:power-cycle <server-id>
railyard server:prune <server-id>
railyard server:resize <server-id> <size>

cordon impede que novas aplicações sejam colocadas em um servidor, sem mover o que já está lá; prune limpa imagens e volumes Docker sem uso.

railyard server:cordon srv-7
railyard server:resize srv-7 s-4vcpu-8gb

Rede

railyard tunnel [app] [web|db|postgres|redis|<process>] [-p local-port]

Alias: proxy. Encaminha uma porta local para um container ou banco de dados no servidor da aplicação — como o fly proxy / railway connect. Escuta em localhost (na porta remota por padrão); um túnel de banco de dados imprime uma URL postgres://…@localhost:<port>/… já pronta para usar. Nada é exposto à internet: os bytes viajam CLI → control plane (seu token) → agente → container.

railyard tunnel my-app db -p 5433

Busca e importações

railyard search:reindex [app]
railyard import

search:reindex roda o comando de reindexação da aplicação em um container novo e descartável. import abre o importador de Heroku/Render/Fly no seu navegador.

Códigos de saída

0 ok · 2 a API retornou um erro (mensagem no stderr) · 3 sem login ativo ou uso incorreto · 64 uso incorreto do comando. Já o railyard run termina com o próprio código de saída do comando remoto.

Veja também

docs/API.md — a API REST com a qual a CLI conversa.