---

name: railway-deploy description: >- Deploys and manages apps on Railway with the Railway CLI: project setup, deploys, services, databases, environment variables, logs and scaling. Use when a user asks to deploy to Railway, check deployment status, set environment variables on Railway, view Railway logs, link a Railway project, add a database on Railway, scale a Railway service, manage Railway environments, redeploy, or run commands with Railway env vars. license: Apache-2.0 compatibility: "Railway CLI 5.x (npm i -g @railway/cli, brew install railway or scoop install railway); Node.js 16+ only for the npm install" metadata: author: terminal-skills version: "1.1.0" category: devops tags: ["railway", "deploy", "cloud", "hosting", "paas"] repository: https://github.com/railwayapp/cli

Railway Deploy

Overview

Deploy, manage, and monitor applications on Railway from the terminal. This skill covers the CLI lifecycle: project setup, service configuration, environment variables, deployments, scaling, logs and debugging. It was checked against Railway CLI 5.63.1 and docs.railway.com (October 2026).

The CLI has no rollback command. Rolling back means redeploying an earlier deployment from the dashboard, or redeploying a known-good commit (see Task H).

Instructions

Task A: Project Setup & Linking

Install the CLI with a package manager if railway is missing:

npm i -g @railway/cli   # or: brew install railway / scoop install railway

Check whether the directory is already linked:

railway status

Otherwise create or link a project:

railway init --name orders-api   # create a project and link this directory
railway link                     # or link an existing project
railway login --browserless      # device-code sign-in on SSH or headless machines

Confirm project, service and environment with railway status. For CI, skip login and export a token (create it in the dashboard, store it as a CI secret):

RAILWAY_TOKEN="$RAILWAY_TOKEN" railway up --ci --service orders-api   # project token: deploys
RAILWAY_API_TOKEN="$RAILWAY_API_TOKEN" railway whoami                 # account token: account-level actions

Task B: Deploy

railway up                         # upload the directory and stream logs
railway up --detach                # start the deploy and return immediately
railway up --ci                    # stream build logs only, then exit
railway up -s orders-api -e staging
railway redeploy                   # redeploy the latest deployment (same build inputs)
railway redeploy --from-source     # pull the newest commit or image from the configured source
railway restart                    # restart without rebuilding
railway down                       # remove the most recent deployment (asks to confirm; -y skips)
railway deployment list --limit 5  # IDs and statuses of recent deployments

railway deploy is not the code-deploy command: it provisions a template (railway deploy --template postgres).

Task C: Services & Resources

railway add --database postgres          # also: mysql, redis, mongo
railway add --service worker --repo orders-team/orders-worker
railway add --service cache --image redis:7
railway service list                     # services in this environment
railway service status                   # deployment status per service
railway scale eu-west=2 us-east=1        # replicas per region (max 50 total)
railway domain                           # generate a *.up.railway.app domain
railway domain shop.northwind-orders.com       # custom domain; prints the DNS records to add
railway volume add --service orders-api --mount-path /data
railway volume list

railway delete removes a whole project, so never run it without the user's explicit confirmation.

Task D: Environment Variables

railway variable list --service orders-api
railway variable set LOG_LEVEL=info PORT=8080
echo "$STRIPE_SECRET" | railway variable set STRIPE_SECRET_KEY --stdin   # keeps the value out of shell history
railway variable set FEATURE_FLAGS=beta --skip-deploys                   # change without triggering a deploy
railway variable delete OLD_API_KEY

By default setting a variable triggers a new deploy. variable list --json and --kv print raw secret values, so do not paste their output into chats or tickets. Services in the same project can reference each other's values with ${{Postgres.DATABASE_URL}} syntax in the dashboard instead of copying them.

Task E: Environments

railway environment list
railway environment new staging
railway environment create staging --duplicate production   # copy production's config
railway environment staging                                   # switch the linked environment
railway environment delete staging --yes

Task F: Logs & Debugging

railway logs                       # stream the latest deployment's logs
railway logs --build               # build logs
railway logs -n 100                # last 100 lines (disables streaming)
railway logs --http                # HTTP request logs; also --network and --dns
railway logs -s orders-api -e production --json
railway ssh                        # shell in the running container
railway connect postgres           # database shell (needs psql, mongosh, etc. installed locally)
railway connect postgres --tunnel-only   # tunnel for TablePlus, DBeaver, pgAdmin

Task G: Local Development

railway run --service orders-api -- npm run migrate   # Railway flags go before the command
railway shell                                          # subshell with Railway variables

railway run injects variables from the linked environment. Run against production only when the user asked for it.

Task H: Health Checks and Rollback

Railway checks a new deployment before switching traffic. Set a health endpoint in the service settings (or healthcheckPath in railway.json); Railway polls it, with the PORT variable and the host healthcheck.railway.app, until it returns 2xx. If it does not within the timeout (default 300 s, adjustable with RAILWAY_HEALTHCHECK_TIMEOUT_SEC), the deployment fails and the previous one stays live. Checks run only at startup, and a service with an attached volume still has brief downtime during deploys.

To verify from a script after railway up --detach:

railway up --detach
for i in $(seq 1 20); do
  code=$(curl -s -o /dev/null -w "%{http_code}" https://orders-api-production.up.railway.app/health)
  [ "$code" = "200" ] && { echo healthy; exit 0; }
  sleep 5
done
echo "unhealthy: check railway logs --build and railway logs"; exit 1

To roll back, open the service's Deployments tab in the dashboard and redeploy an earlier successful deployment, or check out the last good commit and run railway up again.

Examples

Example 1: Deploy a Node.js app from scratch

User request: "Deploy my Node.js app to Railway"

$ railway login
$ railway init --name orders-api
$ railway up
$ railway domain

The CLI uploads the directory, builds it, and prints a deployment URL. railway domain returns a generated orders-api-production.up.railway.app address, and railway status shows project orders-api, environment production.

Example 2: Add Postgres and run migrations

User request: "Add a database to my Railway project and run the Prisma migrations"

$ railway add --database postgres
$ railway variable list --service orders-api   # Postgres variables appear on the new service, not automatically on yours
$ railway variable set DATABASE_URL='${{Postgres.DATABASE_URL}}' --service orders-api
$ railway run --service orders-api -- npx prisma migrate deploy
$ railway redeploy --service orders-api --yes

${{Postgres.DATABASE_URL}} is a reference variable: Railway resolves it at runtime. Note that railway run executes locally, so it needs the database's public (TCP proxy) URL to be reachable from your machine; the private *.railway.internal host only resolves inside Railway. For a private database run the migration as a pre-deploy command in the service settings instead.

Example 3: Debug a crashing deployment

User request: "My Railway deployment keeps crashing"

$ railway deployment list --limit 3 --service orders-api
$ railway logs --build --service orders-api     # did the build fail?
$ railway logs -n 50 --service orders-api       # runtime errors
$ railway variable list --service orders-api    # is DATABASE_URL pointing at localhost?
$ railway variable set DATABASE_URL='${{Postgres.DATABASE_URL}}' --service orders-api

Typical findings: ECONNREFUSED 127.0.0.1:5432 means the database URL is wrong; a healthcheck timeout means the app does not listen on $PORT or on 0.0.0.0.

Guidelines

• Run railway status before changes to confirm project, service and environment.
• Pass -s and -e explicitly in multi-service projects so you do not act on the wrong target.
• Use --detach or --ci in pipelines so the job does not hang on a log stream; RAILWAY_TOKEN is project-scoped, RAILWAY_API_TOKEN account-scoped.
• Most commands accept --json for scripts and --yes to skip confirmation; destructive commands (down, delete, environment delete) need exact selectors and the user's consent.
• Setting variables redeploys; use --skip-deploys when batching changes.
• Never print or share railway variable list, railway run printenv or --json output: it contains secrets.
• Bind the app to 0.0.0.0 and the PORT variable, or healthchecks and public domains fail.
• A deploy is not a rollback: railway down removes the latest deployment, and railway redeploy rebuilds the current one.
• Use Railway's railway.json or railway.toml for build, start and healthcheck settings you want in version control.