Railway CLI Management

Master Railway CLI for deployments, service management, log viewing, and infrastructure operations.

Quick Reference

Deployment

# Deploy current directory to linked service
railway up

# Deploy without attaching to logs
railway up --detach

# Deploy to specific service
railway up --service api

# Deploy to specific environment
railway up --environment production

# Redeploy latest deployment
railway redeploy

# Redeploy specific service
railway redeploy --service worker

# Skip confirmation
railway redeploy --yes

# Remove most recent deployment
railway down

# Remove deployment from specific service
railway down --service api

Service & Project Management

# List all projects
railway list

# Link to existing project (interactive)
railway link

# Link to specific project by ID
railway link <project-id>

# Show current project status
railway status

# Get status as JSON (includes deployment IDs!)
railway status --json

# Open project dashboard in browser
railway open

# Unlink current directory from project
railway unlink

# Link to specific service
railway service <service-name-or-id>

# Add new service to project
railway add

Getting Deployment IDs

Best Method:

# Get full project status including deployment IDs
railway status --json

# Extract specific deployment ID using jq
railway status --json | jq -r '.services.edges[0].node.serviceInstances.edges[0].node.latestDeployment.id'

# Get deployment ID for specific service
railway status --json | jq -r '.services.edges[] | select(.node.name=="api") | .node.serviceInstances.edges[0].node.latestDeployment.id'

Output Structure:

.services.edges[].node - Service info
.node.serviceInstances.edges[].node.latestDeployment.id - Latest deployment UUID
.node.serviceInstances.edges[].node.latestDeployment.meta - Commit info, build config, etc.

Logs

View Logs

# Stream logs for latest deployment
railway logs

# View logs for specific service
railway logs --service api

# View logs for specific environment
railway logs --environment production

# View deployment logs (startup/runtime)
railway logs --deployment

# View build logs
railway logs --build

# View logs for specific deployment by ID
railway logs <deployment-id>

# Get logs for specific service deployment
railway logs --service worker --deployment

# Output as JSON
railway logs --json

# Combine options
railway logs --service api --deployment --json

Logs Tips:

Default: Shows latest deployment logs
Deployment logs: Application startup and runtime output
Build logs: Compilation, dependencies, Nixpacks output
Use --json with jq for filtering

Environment Variables

# List all variables for active environment
railway variables

# List for specific service
railway variables --service api

# List for specific environment
railway variables --environment production

# Show as key=value format
railway variables --kv

# Output as JSON
railway variables --json

# Set variable(s)
railway variables --set "DATABASE_URL=postgres://..."

# Set multiple
railway variables --set "NODE_ENV=production" --set "LOG_LEVEL=debug"

# Run local command with Railway variables
railway run npm start

# Open subshell with Railway variables loaded
railway shell

Environments

# Link to environment (interactive)
railway environment

# Link to specific environment
railway environment production

# Create new environment
railway environment new

# Delete environment
railway environment delete <environment-name>

Scaling

# Scale service in linked environment
railway scale --us-west1 3

# Scale specific service
railway scale --service api --us-west1 2

# Scale across multiple regions
railway scale --us-west1 2 --europe-west4 1

# Available regions:
# --us-west1, --us-west2, --us-east4
# --europe-west4, --asia-southeast1

Volumes

# List volumes
railway volume list

# List for specific service
railway volume list --service api

# Add new volume
railway volume add

# Delete volume
railway volume delete <volume-id>

# Update volume
railway volume update <volume-id>

# Detach volume from service
railway volume detach <volume-id>

# Attach volume to service
railway volume attach <volume-id>

Database Connection

# Connect to database shell
railway connect

# Examples:
# - PostgreSQL: Opens psql
# - MongoDB: Opens mongosh
# - MySQL: Opens mysql
# - Redis: Opens redis-cli

Authentication

# Login to Railway account
railway login

# Logout
railway logout

# Check current user
railway whoami

Common Workflows

Initial Project Setup

# Login
railway login

# Link to existing project
railway link

# Or create new project
railway init

# Link to service
railway service api

# Link to environment
railway environment production

# Check status
railway status

Deploy with Environment Variables

# Set variables
railway variables --set "NODE_ENV=production" --set "API_KEY=secret"

# Deploy
railway up

# Monitor logs
railway logs --deployment

Debug Failed Deployment

# Get deployment ID
DEPLOY_ID=$(railway status --json | jq -r '.services.edges[0].node.serviceInstances.edges[0].node.latestDeployment.id')

# View build logs
railway logs $DEPLOY_ID --build

# View deployment logs
railway logs $DEPLOY_ID --deployment

# Check full status
railway status --json | jq '.services.edges[].node.serviceInstances.edges[].node.latestDeployment'

Monitor Multiple Services

# Terminal 1: API logs
railway logs --service api --deployment

# Terminal 2: Worker logs
railway logs --service worker --deployment

# Or use JSON + jq for filtering
railway logs --service api --json | jq 'select(.level == "error")'

Extract Deployment Information

# Get all deployment IDs
railway status --json | jq -r '.services.edges[].node | {service: .name, deployment: .serviceInstances.edges[0].node.latestDeployment.id}'

# Get commit info for deployment
railway status --json | jq -r '.services.edges[].node.serviceInstances.edges[].node.latestDeployment.meta | {commit: .commitHash, message: .commitMessage}'

# Get service URLs
railway status --json | jq -r '.services.edges[].node | select(.serviceInstances.edges[0].node.latestDeployment.canRedeploy == true)'

Redeploy After Config Change

# Change variables
railway variables --set "NEW_VAR=value"

# Redeploy to pick up changes
railway redeploy --yes

# Or deploy fresh
railway up

Run Commands with Railway Environment

# Run migration
railway run npm run migrate

# Run seed script
railway run node scripts/seed.js

# Start local dev with production variables
railway run npm run dev

# Open shell with all variables
railway shell

Important Notes

Deployment Targets

Production: Linked to production environment
Preview: Branch-based deployments (configured in Railway dashboard)
Development: Local with railway run or railway shell

JSON Output

railway status --json is the most comprehensive command
Contains: services, deployment IDs, commit info, build config, service instances
Use jq for parsing and filtering

Environment Linking

Project, service, and environment are all linked separately
Use railway status to verify what you’re linked to
Change with railway service, railway environment, railway link

Logs Behavior

Default: Latest deployment logs (5-minute window)
Deployment logs: Application output (stdout/stderr)
Build logs: Nixpacks, dependencies, compilation
JSON output: Structured logs for parsing

Railway.json Configuration

Stored in project root
Defines build/deploy configuration per service
Example:

{
  "$schema": "https://railway.app/railway.schema.json",
  "build": {
    "builder": "NIXPACKS",
    "buildCommand": "pnpm install && pnpm run build"
  },
  "deploy": {
    "startCommand": "node dist/index.js",
    "healthcheckPath": "/health",
    "healthcheckTimeout": 100,
    "restartPolicyType": "ON_FAILURE",
    "restartPolicyMaxRetries": 10
  }
}

Common Issues

No TTY errors: Command requires interactive input (use JSON output or flags)
Service not linked: Run railway service <service-name> first
Environment not linked: Run railway environment <env-name> first
Deployment not found: Use railway status --json to verify deployment ID exists

Examples from Real Projects

Saturn Backend (API + Worker)

# Check both services status
railway status --json | jq '.services.edges[] | {
  service: .node.name,
  deployment: .node.serviceInstances.edges[0].node.latestDeployment.id,
  commit: .node.serviceInstances.edges[0].node.latestDeployment.meta.commitHash
}'

# Get API deployment logs
railway logs --service api --deployment

# Get worker deployment logs
railway logs --service worker --deployment

# Redeploy both after config change
railway redeploy --service api --yes
railway redeploy --service worker --yes

Debug Production Issue

# Stream live logs with error filtering
railway logs --service api --deployment --json | jq 'select(.level == "error" or .level == "fatal")'

# Get recent deployment metadata
railway status --json | jq '.services.edges[] | select(.node.name == "api") | .node.serviceInstances.edges[0].node.latestDeployment.meta'

# Check health check configuration
railway status --json | jq '.services.edges[].node.serviceInstances.edges[].node.latestDeployment.meta.fileServiceManifest.deploy'

railway-cli

快捷安装