Railway CLI Management

Railway CLI Management

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

Quick Reference

Deployment

# Deploy current directory to linked servicerailway up# Deploy without attaching to logsrailway up --detach# Deploy to specific servicerailway up --service api# Deploy to specific environmentrailway up --environment production# Redeploy latest deploymentrailway redeploy# Redeploy specific servicerailway redeploy --service worker# Skip confirmationrailway redeploy --yes# Remove most recent deploymentrailway down# Remove deployment from specific servicerailway down --service api

Service & Project Management

# List all projectsrailway list# Link to existing project (interactive)railway link# Link to specific project by IDrailway link <project-id># Show current project statusrailway status# Get status as JSON (includes deployment IDs!)railway status --json# Open project dashboard in browserrailway open# Unlink current directory from projectrailway unlink# Link to specific servicerailway service <service-name-or-id># Add new service to projectrailway add

Getting Deployment IDs

Best Method:

# Get full project status including deployment IDsrailway status --json# Extract specific deployment ID using jqrailway status --json | jq -r '.services.edges[0].node.serviceInstances.edges[0].node.latestDeployment.id'# Get deployment ID for specific servicerailway 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 deploymentrailway logs# View logs for specific servicerailway logs --service api# View logs for specific environmentrailway logs --environment production# View deployment logs (startup/runtime)railway logs --deployment# View build logsrailway logs --build# View logs for specific deployment by IDrailway logs <deployment-id># Get logs for specific service deploymentrailway logs --service worker --deployment# Output as JSONrailway logs --json# Combine optionsrailway 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 environmentrailway variables# List for specific servicerailway variables --service api# List for specific environmentrailway variables --environment production# Show as key=value formatrailway variables --kv# Output as JSONrailway variables --json# Set variable(s)railway variables --set "DATABASE_URL=postgres://..."# Set multiplerailway variables --set "NODE_ENV=production" --set "LOG_LEVEL=debug"# Run local command with Railway variablesrailway run npm start# Open subshell with Railway variables loadedrailway shell

Environments

# Link to environment (interactive)railway environment# Link to specific environmentrailway environment production# Create new environmentrailway environment new# Delete environmentrailway environment delete <environment-name>

Scaling

# Scale service in linked environmentrailway scale --us-west1 3# Scale specific servicerailway scale --service api --us-west1 2# Scale across multiple regionsrailway scale --us-west1 2 --europe-west4 1# Available regions:# --us-west1, --us-west2, --us-east4# --europe-west4, --asia-southeast1

Volumes

# List volumesrailway volume list# List for specific servicerailway volume list --service api# Add new volumerailway volume add# Delete volumerailway volume delete <volume-id># Update volumerailway volume update <volume-id># Detach volume from servicerailway volume detach <volume-id># Attach volume to servicerailway volume attach <volume-id>

Database Connection

# Connect to database shellrailway connect# Examples:# - PostgreSQL: Opens psql# - MongoDB: Opens mongosh# - MySQL: Opens mysql# - Redis: Opens redis-cli

Authentication

# Login to Railway accountrailway login# Logoutrailway logout# Check current userrailway whoami

Common Workflows

Initial Project Setup

# Loginrailway login# Link to existing projectrailway link# Or create new projectrailway init# Link to servicerailway service api# Link to environmentrailway environment production# Check statusrailway status

Deploy with Environment Variables

# Set variablesrailway variables --set "NODE_ENV=production" --set "API_KEY=secret"# Deployrailway up# Monitor logsrailway logs --deployment

Debug Failed Deployment

# Get deployment IDDEPLOY_ID=$(railway status --json | jq -r '.services.edges[0].node.serviceInstances.edges[0].node.latestDeployment.id')# View build logsrailway logs $DEPLOY_ID --build# View deployment logsrailway logs $DEPLOY_ID --deployment# Check full statusrailway status --json | jq '.services.edges[].node.serviceInstances.edges[].node.latestDeployment'

Monitor Multiple Services

# Terminal 1: API logsrailway logs --service api --deployment# Terminal 2: Worker logsrailway logs --service worker --deployment# Or use JSON + jq for filteringrailway logs --service api --json | jq 'select(.level == "error")'

Extract Deployment Information

# Get all deployment IDsrailway status --json | jq -r '.services.edges[].node | {service: .name, deployment: .serviceInstances.edges[0].node.latestDeployment.id}'# Get commit info for deploymentrailway status --json | jq -r '.services.edges[].node.serviceInstances.edges[].node.latestDeployment.meta | {commit: .commitHash, message: .commitMessage}'# Get service URLsrailway status --json | jq -r '.services.edges[].node | select(.serviceInstances.edges[0].node.latestDeployment.canRedeploy == true)'

Redeploy After Config Change

# Change variablesrailway variables --set "NEW_VAR=value"# Redeploy to pick up changesrailway redeploy --yes# Or deploy freshrailway up

Run Commands with Railway Environment

# Run migrationrailway run npm run migrate# Run seed scriptrailway run node scripts/seed.js# Start local dev with production variablesrailway run npm run dev# Open shell with all variablesrailway 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 statusrailway 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 logsrailway logs --service api --deployment# Get worker deployment logsrailway logs --service worker --deployment# Redeploy both after config changerailway redeploy --service api --yesrailway redeploy --service worker --yes

Debug Production Issue

# Stream live logs with error filteringrailway logs --service api --deployment --json | jq 'select(.level == "error" or .level == "fatal")'# Get recent deployment metadatarailway status --json | jq '.services.edges[] | select(.node.name == "api") | .node.serviceInstances.edges[0].node.latestDeployment.meta'# Check health check configurationrailway status --json | jq '.services.edges[].node.serviceInstances.edges[].node.latestDeployment.meta.fileServiceManifest.deploy'