CLI · Docs · Railyard

railyard es un solo binario de Go sobre la API REST de Railyard: despliega, sigue logs, ejecuta comandos, administra variables de entorno, dominios, bases de datos y servidores desde tu terminal. No necesitas ningún runtime.

Instalación

Un solo binario, sin dependencias, para macOS y Linux en arm64 y amd64. Nada está fijo de antemano — la CLI habla con el Railyard en el que inicies sesión.

brew install almokhtarbr/railyard/railyard           # Homebrew
curl -fsSL https://app.railyard.run/install.sh | sh   # instalador en una línea (verifica el sha256)

Más adelante, en lugar de brew upgrade:

railyard upgrade   # reemplaza este binario con el build más reciente que ofrece tu Railyard
railyard version   # imprime el build instalado

Inicia sesión

railyard login

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

Este es el flujo de dispositivo (la misma idea que gh auth login o fly auth login): la CLI abre esa URL en tu navegador, escribes el código que aparece en la terminal en el panel donde ya iniciaste sesión, y la CLI recoge un token generado para ti — nunca escribes una contraseña o token en la terminal. Inicia sesión en app.railyard.run; configura RAILYARD_API para apuntarla a otro lugar.

Tus tokens de API, claves SSH, cuentas de nube y proveedores de Git están en una sola página del panel: Configuración → Acceso y tokens (app.railyard.run/access).

railyard whoami    # equipo, scope del token, límites (alias: me)
railyard logout    # olvida el token guardado

Configuración y CI

El token y la URL de la API se guardan en ~/.railyard/config.json (modo 0600). Para CI o contenedores, omite login y configura variables de entorno en su lugar — siempre tienen prioridad sobre el archivo:

Variable	Sobrescribe
`RAILYARD_API` (o `RAILYARD_API_URL`)	la URL del control plane
`RAILYARD_TOKEN`	el bearer token
`RAILYARD_CONFIG`	la ruta del archivo de configuración (por defecto `~/.railyard/config.json`)

--json en cualquier comando imprime la respuesta cruda de la API en lugar de una tabla.

Vincula una app a un directorio

cd my-app && railyard link my-app   # escribe ./.railyard.json: {"app": "my-app"}
railyard deploy --follow            # el argumento app ahora es opcional en este directorio
railyard unlink

Los comandos que aceptan [app] recurren a la app vinculada, que se encuentra subiendo desde el directorio actual hasta el primer .railyard.json. En cualquier otro lugar, <app> es un id o un nombre (un prefijo sin ambigüedad también funciona).

Autocompletado de shell

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

Apps

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 · nombre · estado del último despliegue · url, uno por línea.
app — JSON completo de una app.
open — imprime y abre la URL de la app en tu navegador.
create flags: --server <id|hostname>, --ref <branch>, --port <n> (detectado del repositorio si se omite), --addons postgres,redis,…, --db-extensions <ext,…>.
templates — el catálogo de un clic; launch despliega una ahora.
clone — copia la app en una copia de staging; promote lleva el release de una copia de staging a producción (como los pipelines de Heroku).

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

Despliegues

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> despliega esa ref una sola vez sin cambiar la rama rastreada, --message "note", --follow transmite el log del build y del release, --force omite las comprobaciones del primer despliegue, --at <ISO 8601> lo programa (cancela con deploy:cancel), --anyway despliega fuera de la ventana de despliegue.

deploy --local construye el directorio actual con tu propio Docker en lugar del builder del equipo, lo sube, y despliega esa imagen una sola vez — como fly deploy --local-only:

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

--image sube a tu propio registry (tu docker login) en lugar del registry de build del equipo; un repo sin tag obtiene :local-<UTC timestamp>.

deploy-window — los push y auto-despliegues fuera de la ventana esperan hasta que se abre; deploy --anyway la anula. rollback vuelve a desplegar el commit de un release anterior y restaura sus variables de entorno (--code-only conserva las de hoy).

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

Despliegues por Git

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

git:remote agrega un remote de git llamado railyard que apunta a esta app, y un credential helper de git que responde con tu token, así que git push railyard main despliega ese commit exacto y transmite el log de build de regreso. git:strict (activado por defecto) rechaza un push cuyo build falla, así que la rama se queda en su commit anterior; off acepta el push primero y despliega después.

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

Cada push tiene un límite de 1 GB. Los repositorios subidos por push también cuentan contra una cuota por equipo (5 GB por defecto); pasarla rechaza el push mostrando el uso y una sugerencia de eliminar apps a las que ya no le haces push. Railyard corre git gc sobre los repositorios subidos por push cada noche para mantenerlos pequeños.

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 un contenedor nuevo de un solo uso desde el release actual (como heroku run), o ejecuta dentro del contenedor que ya está corriendo con --exec; transmite la salida y termina con el código de salida del comando remoto. sleep detiene los contenedores de la app después de esos minutos de inactividad, y wake o la siguiente solicitud los reactiva; off lo desactiva.

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

Variables de configuración y dominios

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 los valores a menos que uses --reveal (todos) o --reveal KEY (uno). configs lista las entradas de configuración de todo el equipo (solo lectura desde la 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

Base de datos y volúmenes

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 es de solo lectura a menos que uses --write (necesita un token con scope de escritura). db:url devuelve un enlace de descarga firmado para una copia de seguridad.

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 la app como un railyard.yml (--secrets incluye los valores de las variables); manifest:apply aplica uno a la app. manifest:validate verifica un archivo local (./railyard.yml si se omite) sin aplicarlo ni necesitar ninguna app — las claves desconocidas reciben una sugerencia (contaner_port → “did you mean container_port?”); termina con 0 e imprime “is valid” si no hay problemas, o termina con 1 y los lista.

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

Observabilidad

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

metrics imprime solicitudes, p95, tasa de error y los endpoints más lentos. autoscale escala las réplicas web entre --min/--max cuando la latencia p95 o la CPU cruza los umbrales dados; off elimina los límites.

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

Notificaciones y webhooks

railyard notify
railyard webhooks

Listados de todo el equipo con las reglas de notificación y los endpoints de webhook (solo lectura desde la CLI; créalos y edítalos desde el panel).

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 evita que se coloquen apps nuevas en un servidor sin mover lo que ya está ahí; prune limpia las imágenes y volúmenes de Docker sin usar.

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

Red

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

Alias: proxy. Reenvía un puerto local a un contenedor o base de datos en el servidor de la app — como fly proxy / railway connect. Escucha en localhost (el puerto remoto por defecto); un túnel de base de datos imprime una URL postgres://…@localhost:<port>/… ya lista. Nada se abre a internet: los bytes viajan CLI → control plane (tu token) → agente → contenedor.

railyard tunnel my-app db -p 5433

Búsqueda e importaciones

railyard search:reindex [app]
railyard import

search:reindex corre el comando de reindexado de la app en un contenedor nuevo de un solo uso. import abre el importador de Heroku/Render/Fly en tu navegador.

Códigos de salida

0 ok · 2 la API devolvió un error (mensaje en stderr) · 3 no hay sesión iniciada o uso incorrecto · 64 uso incorrecto del comando. railyard run en cambio termina con el código de salida del comando remoto.

Ver también

docs/API.md — la API REST con la que habla la CLI.