CLI
Deploy, tail logs, run commands and manage apps from your terminal.
railyard is a single Go binary over the Railyard REST API:
deploy, tail logs, run commands, manage env vars, domains, databases and
servers from your terminal. No runtime required.
Install
One binary, no dependencies, for macOS and Linux on arm64 and amd64. Nothing is hardcoded — the CLI talks to whichever Railyard you sign in to.
brew install almokhtarbr/railyard/railyard # Homebrew
curl -fsSL https://app.railyard.run/install.sh | sh # one-line installer (verifies the sha256)
Later, instead of brew upgrade:
railyard upgrade # replaces this binary with the newest build your Railyard serves
railyard version # prints the installed build
Sign in
railyard login
Confirm code ABCD2345 in your browser: https://app.railyard.run/cli/auth/ABCD2345
Logged in to https://app.railyard.run
This is the device flow (same idea as gh auth login or fly auth login):
the CLI opens that URL in your browser, you type the code shown in the
terminal into the already-signed-in dashboard, and the CLI picks up a token
minted for you — no password or token ever typed into the terminal. It signs in
to app.railyard.run; set RAILYARD_API to point it somewhere else.
Your API tokens, SSH keys, cloud accounts and Git providers are on one page in the dashboard: Settings → Access & tokens (app.railyard.run/access).
railyard whoami # team, token scope, limits (alias: me)
railyard logout # forget the saved token
Config and CI
The token and API URL are saved to ~/.railyard/config.json (mode 0600).
For CI or containers, skip login and set environment variables instead —
they always win over the file:
| Variable | Overrides |
|---|---|
RAILYARD_API (or RAILYARD_API_URL) | the control plane URL |
RAILYARD_TOKEN | the bearer token |
RAILYARD_CONFIG | the config file path (default ~/.railyard/config.json) |
--json on any command prints the raw API response instead of a table.
Linking an app to a directory
cd my-app && railyard link my-app # writes ./.railyard.json: {"app": "my-app"}
railyard deploy --follow # app argument now optional in this directory
railyard unlink
Commands that take [app] fall back to the linked app, found by walking up
from the current directory to the first .railyard.json. Everywhere else,
<app> is an id or a name (an unambiguous prefix works too).
Shell completion
railyard completion zsh > "${fpath[1]}/_railyard"
railyard completion bash > /etc/bash_completion.d/railyard
railyard completion fish > ~/.config/fish/completions/railyard.fish
Status, progress and scripting
railyard status # who you are, every app's last deploy, servers, and anything running now
railyard doctor # checks sign-in, API latency, the linked app, your version and local tools
railyard jobs [--follow] # backups, imports, forks, upgrades and other long work, with live progress
railyard jobs:wait <kind> <id> # attach to one job and show its progress bar until it finishes
railyard jobs:cancel <kind> <id> # stop a running job (--json shows which jobs are cancellable)
Long operations print a progress bar with the current step, percent and time
left. db:backup, db:fork, db:upgrade and volume:backup take --wait to
stay attached until the work is done and exit non-zero if it fails — so a
script can run railyard db:backup my-app --wait && ./migrate.sh. Without
--wait they return at once and print the jobs:wait command to reattach.
On a terminal the bar redraws in place; in CI logs it prints one line per step.
Every command takes --json. Output is the API’s own JSON on stdout, nothing
else, and errors come back as {"error": "...", "code": N} with the same exit
code — safe to pipe into jq:
railyard apps --json | jq -r '.[].name'
railyard status --json | jq '.jobs | length'
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]
railyard apps:rm <app> --confirm <name>
apps— id · name · last deploy status · url, one per line.app— full JSON for one app.open— prints and opens the app’s URL in your browser.createflags:--server <id|hostname>,--ref <branch>,--port <n>(detected from the repo when omitted),--addons postgres,redis,…,--db-extensions <ext,…>.templates— the one-click catalog;launchdeploys one now.apps:rm— deletes the app, its deploys, logs and databases; you must pass its exact name to--confirm.clone— copies the app into a staging copy;promoteships a staging app’s release to production (like Heroku pipelines).
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]
deploy flags: --ref <branch|tag|sha> deploys that ref once without
changing the tracked branch, --message "note", --follow streams the
build and release log, --force skips first-deploy checks, --at <ISO 8601>
schedules it (cancel with deploy:cancel), --anyway deploys outside the
deploy window.
deploy --local builds the current directory with your Docker instead of
the team’s builder, pushes it, and deploys that image once — like
fly deploy --local-only:
railyard deploy [app] --local [--image repo[:tag]]
--image pushes to your own registry (your docker login) instead of the
team’s build registry; an untagged repo gets :local-<UTC timestamp>.
deploy-window — pushes and auto-deploys outside the window wait until it
opens; deploy --anyway overrides it. rollback redeploys an earlier
release’s commit and restores its env vars (--code-only keeps today’s).
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
Git deploys
railyard git:remote [app] [--remote name]
railyard git:strict <app> on|off
git:remote adds a railyard git remote pointing at this app and a git
credential helper that answers with your token, so git push railyard main
deploys that exact commit and streams the build log back. git:strict
(on by default) rejects a push whose build fails, so the branch stays on its
old commit; off accepts the push first and deploys after.
cd my-app && railyard git:remote
git push railyard main
Each push is capped at 1 GB. Pushed repositories also count against a
per-team quota (5 GB by default); going over it rejects the push with the
usage and a suggestion to delete apps you no longer push to. Railyard runs
git gc on pushed repositories every night to keep them small.
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] [-it] -- <command...>
railyard ssh [app] [process] [--shell bash|rails|tinker|django|node|python]
railyard console [app] [process]
railyard server:ssh <server-id>
railyard scale <app> <process>=<n> …
railyard wake [app]
railyard sleep <app> <10|30|60|360|1440|off>
run starts a fresh one-off container from the current release (like
heroku run), or execs inside the already-running container with --exec;
it streams output and exits with the remote command’s own exit code.
run -it attaches your terminal to the command inside a running container,
for anything that asks questions (createsuperuser, a REPL, a TUI).
ssh opens a full interactive shell inside a running container — arrow keys,
tab completion, colors and resizing all work, and you leave with the shell’s
own exit code. console picks the app’s framework console for you (rails console, php artisan tinker, manage.py shell, node, python) and falls
back to bash. server:ssh is a root shell on the server itself, for team
owners. All three go through Railyard’s encrypted channel — no SSH key, open
port or bastion needed — and each session is recorded in the activity log.
They need a read-write token from a team admin; the session can also be opened
from the dashboard’s Console tab.
sleep stops the app’s containers after that many idle minutes and
wake/the next request brings it back; off disables it.
railyard logs my-app --follow --process web
railyard run my-app -- bin/rails db:migrate
railyard console my-app
railyard ssh my-app worker --shell bash
railyard scale my-app web=2 worker=1
railyard sleep my-app 30
Config vars and domains
railyard env [app] [--reveal[=KEY]]
railyard env:set <app> KEY=VALUE …
railyard env:unset <app> KEY
railyard env:pull [app] [-o .env] [--overwrite]
railyard env:push [app] [file] [--replace] [--dry-run]
railyard env:diff <app> <other-app|file> [--reveal]
railyard env:edit [app]
railyard configs
railyard domains [app]
railyard domain:add <app> <hostname> [--redirect]
railyard domain:rm <app> <domain-id>
railyard domains:wait <app> <hostname> [--timeout 15m]
railyard domains:check <app> <hostname>
env masks values unless --reveal (all) or --reveal KEY (one).
configs lists team-wide config entries (read-only from the CLI).
domains:wait follows a new domain from DNS verification through the
certificate until it’s live over HTTPS, printing the DNS records to add while
it waits — handy right after domain:add in a setup script. domains:check
re-checks DNS and the certificate immediately instead of on the next automatic
check.
env:pull writes the app’s variables to a .env file (readable only by you)
and refuses to overwrite one without --overwrite. env:push sets what’s in
the file and shows a +/~/- summary; --replace also removes variables
that aren’t in the file, and --dry-run shows the summary without changing
anything. env:diff compares two apps (say production and staging) or an app
and a file, masking values unless --reveal. env:edit opens the variables in
$EDITOR and applies whatever you save. Sealed variables are never written to
disk and are never changed or removed by these commands. Changes take effect on
the next deploy or restart.
railyard env my-app --reveal SECRET_KEY_BASE
railyard env:set my-app RAILS_ENV=production LOG_LEVEL=info
railyard env:diff my-app my-app-staging
railyard env:pull my-app && railyard env:push my-app-staging .env --dry-run
railyard domain:add my-app www.example.com --redirect
Database and 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 is read-only unless --write (needs a write-scoped token).
db:url returns a signed download link for a backup.
railyard db:query my-app "select count(*) from users"
railyard db:backup my-app
railyard volume:backup my-app data
Moving data in and out
railyard db:import <app> <dump-file|database-url> [--confirm <app>] [--add] [--no-backup] [--no-deploy] [--no-wait]
railyard db:imports [app] [--follow]
railyard db:export [app] [-o file] [--from <backup-id>]
railyard db:pull <app> <local-database-url>
railyard db:push <local-database-url> <app> --confirm <app>
railyard db:connect [app]
db:import takes a .sql, .sql.gz, pg_dump custom .dump or .tar
file up to 5 GB, or the URL of another Postgres or MySQL database to copy
from. Plain SQL is compressed before it leaves your machine. The upload goes
straight to storage in parallel chunks and is resumable — if the connection
drops, run the same command again and only the missing chunks are sent. The
app’s database is backed up first and restored automatically if the import
fails. Replacing a database that already has data needs --confirm <app>;
--add loads the dump on top of what’s there instead.
db:export takes a fresh backup, waits for it and downloads it in one step.
db:pull streams the app’s database into a local one and db:push sends a
local database up through the same safe import path (backup first, rollback on
failure). db:connect opens psql or mysql through an encrypted tunnel — no
database port is ever opened to the internet. These use your local
pg_dump/pg_restore/psql (or mysqldump/mysql); railyard doctor
shows which are installed.
railyard db:import my-app ./production.sql --confirm my-app
railyard db:import my-app postgres://user:pass@old-host:5432/shop --confirm my-app
railyard db:pull my-app postgres://localhost/my_app_development
railyard db:export my-app -o before-launch.dump
Inspecting a live database
railyard db:info [app] # size, connections in use, cache and index hit rates
railyard db:tables [app] # tables by size with row estimates
railyard db:ps [app] # queries running right now
railyard db:locks [app] # queries waiting on a lock, and the query holding it
railyard db:outliers [app] # the queries that take the most total time
railyard db:unused-indexes [app] # indexes that are never read
railyard db:seq-scans [app] # large tables read without an index
railyard db:kill [app] <pid> [--force]
db:kill stops one query; --force ends its whole connection. These need a
read-write token, and all but db:tables are Postgres-only. db:outliers uses the
pg_stat_statements extension and says how to enable it if it’s missing.
Manifest
railyard manifest:pull [app] [--secrets] [--out railyard.yml]
railyard manifest:apply [app] <file.yml>
railyard manifest:validate [file.yml]
manifest:pull prints the app as a railyard.yml (--secrets includes
variable values); manifest:apply applies one to the app. manifest:validate
checks a local file (./railyard.yml if omitted) without applying it or
needing an app at all — unknown keys get a suggestion (contaner_port →
“did you mean container_port?”); exits 0 and prints “is valid” with no
problems, or exits 1 and lists them.
railyard manifest:pull my-app --out railyard.yml
railyard manifest:apply my-app railyard.yml
railyard manifest:validate railyard.yml
Observability
railyard metrics [app] [--range 1h|24h|7d|30d]
railyard autoscale <app> --max N [--min N] [--p95 ms] [--cpu %]
railyard autoscale <app> off
metrics prints requests, p95, error rate and slowest endpoints.
autoscale scales web replicas between --min/--max once p95 latency or
CPU crosses the given thresholds; off removes the bounds.
railyard metrics my-app --range 7d
railyard autoscale my-app --max 5 --min 1 --p95 300 --cpu 80
Notifications and webhooks
railyard notify
railyard webhooks
Team-wide listings of notification rules and webhook endpoints (read-only from the CLI; create and edit them from the dashboard).
Cloud account, certificates, secret files, alerts
railyard usage # this month's Railyard Cloud usage
railyard sizes # server sizes you can create
railyard ssh-keys # SSH keys on your cloud account
railyard ssh-keys:add laptop ~/.ssh/id_ed25519.pub
railyard ssh-keys:rm 4
railyard certs myapp # certificates you uploaded for an app
railyard certs:add myapp --cert fullchain.pem --key privkey.pem
railyard certs:rm myapp 7
railyard secret-files myapp # files mounted into the app (service accounts, keys)
railyard secret-files:add myapp service-account.json ./sa.json
railyard secret-files:rm myapp 2
railyard metric-alerts myapp # CPU / memory / response-time alerts
railyard metric-alerts:add myapp cpu 80 5 # fire when CPU stays above 80% for 5 minutes
railyard metric-alerts:rm myapp 1
railyard canary:promote 40 # send all traffic to the canary deploy
railyard canary:stop 40 # roll the canary back
Every command takes --json for the raw API response.
Databases, tunnels, pooler, profiles, images, OpenTelemetry
railyard db:forks myapp # database forks (copies for a branch or a test)
railyard db:fork myapp --target-app myapp-staging --mask-sql ./mask.sql
railyard db:forks:rm myapp 3
railyard db:replicas 2 # streaming replicas of the database server 2
railyard db:replicas:add 2 3 # make server 3 a replica of server 2
railyard db:replicas:promote 2 9 # promote replica 9
railyard db:replicas:rm 2 9
railyard db:upgrades 2 # Postgres major upgrades on server 2
railyard db:upgrade 2 postgres:17 --when window # now, or in the next maintenance window
railyard db:upgrade:rollback 2 1
railyard db:upgrade:cancel 2 1
railyard tunnel myapp --target db --local-port 5433 # one-off tunnel to the app's database
railyard registry myapp # the app's private image registry
railyard pooler 2 · railyard pooler:add 2 · railyard pooler:rm 2 # connection pooler on a database server
railyard external-db:attach myapp postgres postgres://user:pass@host/db --copy
railyard external-db:detach myapp postgres
railyard profiles # deployment profiles shared by your apps
railyard profiles:add name=rails build_method=dockerfile release_command="bin/rails db:migrate" health_path=/up
railyard profiles:set 1 health_path=/healthz
railyard profiles:rm 1
railyard images · railyard images:rm <id> # Railyard Cloud server images
railyard otel myapp # OpenTelemetry export settings
railyard otel:set myapp endpoint=https://otel.example.com protocol=http
railyard otel:rm myapp
railyard image-watch:check myapp # check the app's image for a newer tag now
railyard redis myapp # shared or dedicated Redis, memory, eviction policy
railyard redis:set myapp dedicated=true maxmemory_mb=256 policy=allkeys-lru
railyard data-move myapp 3 # move the app's databases and add-ons to database server 3
railyard process-types myapp # processes: command, replicas, size, limits
railyard process-types:set myapp worker size=m kill_timeout_seconds=60
railyard deploy-strategy myapp canary canary_steps=10,50,100 canary_promote_after_minutes=10
railyard deploy-strategy myapp standard
Team, tokens and activity
railyard activity [app] [--follow] [--all]
railyard members
railyard members:invite <email> [--role viewer|deployer|admin|owner] [--apps a,b]
railyard members:role <email|id> <role>
railyard members:rm <email|id>
railyard tokens
railyard tokens:create <name> [--scope read|deploy|write] [--app <app>] [--expires-in-days N]
railyard tokens:revoke <id>
railyard sessions
railyard sessions:revoke <id> | --all
railyard approvals
railyard approvals:reject <id>
railyard apps:rename <app> <new-name>
activity is the audit log — deploys, config changes, consoles, imports and
more — newest first, for one app or (with --all, or outside a linked
directory) the whole team; --follow streams new entries as they happen.
members:rm also cancels a pending invitation. tokens:create prints the new
token alone on stdout so it can go straight into a CI secret; it’s shown once.
sessions lists the browsers signed in to your account. approvals shows
actions waiting on a teammate’s phone; approving needs the phone itself,
rejecting works from here. apps:rename also updates the directory link.
railyard activity my-app --follow
railyard members:invite dev@example.com --role deployer --apps my-app
railyard tokens:create github-actions --scope deploy --app my-app --expires-in-days 90
Servers
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>
railyard standby:rejoin <server-id>
railyard providers
railyard regions [provider] [--sizes]
railyard server:create [--provider vultr] [--region fra] [--size …] [--role database] [--no-wait]
railyard server:metrics <server-id> [--range 1h|6h|24h|7d|30d]
railyard server:block-ip <ip|cidr>
railyard server:unblock-ip <ip|cidr>
railyard server:trust-ip <server-id> <ip>
railyard maintenance-window [server-id] [--day sun --hour 3 --hours 2]
railyard cloud:servers
railyard cloud:servers:create <name> --size <size> [--image <id>] [--ssh-key name]
railyard cloud:servers:destroy <id> --confirm <name>
cordon stops new apps from being placed on a server without moving what’s
already there; prune clears unused Docker images and volumes; standby:rejoin re-attaches a
server that lost a database failover as a standby of the new primary.
server:create orders a server from a cloud provider your team connected
(DigitalOcean, Vultr, Hetzner, AWS, OVH, Scaleway or UpCloud), sets it up
for Railyard, and shows each step with a progress bar until it’s ready for
deploys. With one provider connected, --provider is optional; regions and
regions --sizes list the slugs. server:metrics shows CPU, memory, disk and
load now and at their peak over the range. server:block-ip blocks an address
or range on every server in the team at once; server:trust-ip makes sure one
is never banned. maintenance-window shows or sets when OS updates and
database upgrades may run, for the whole team or one server. cloud:servers
manage servers on Railyard Cloud, billed hourly.
railyard server:cordon srv-7
railyard server:resize srv-7 s-4vcpu-8gb
railyard server:create --provider hetzner --region fsn1
railyard server:block-ip 203.0.113.0/24
railyard maintenance-window --day sun --hour 3 --hours 2
Networking
railyard tunnel [app] [web|db|postgres|redis|<process>] [-p local-port]
Alias: proxy. Forwards a local port to a container or database on the
app’s server — like fly proxy / railway connect. Listens on localhost
(the remote port by default); a database tunnel prints a ready
postgres://…@localhost:<port>/… URL. Nothing is opened to the internet:
bytes travel CLI → control plane (your token) → agent → container.
railyard tunnel my-app db -p 5433
Search and imports
railyard search:reindex [app]
railyard import
search:reindex runs the app’s reindex command in a fresh one-off
container. import opens the Heroku/Render/Fly importer in your browser.
Exit codes
0 ok · 2 the API returned an error (message on stderr) · 3 not signed
in or bad usage · 64 bad command usage. railyard run instead exits with
the remote command’s own exit code.
See also
docs/API.md— the REST API the CLI talks to.