Railway CLI Skill

Fast reference for Railway CLI operations. See REFERENCE.md for comprehensive documentation.

Overview

What is Railway: Modern PaaS for instant deployments with zero configuration. Supports any language/framework via Nixpacks or Dockerfile. Includes managed databases, private networking, and automatic SSL.

When to Use: Deploying apps, managing services/databases, debugging (logs, SSH), configuring domains, managing environment variables, CI/CD integration.

Auto-Detection:

railway.json

railway.toml

RAILWAY_TOKEN

.env

Table of Contents

1. Overview
2. Critical: Avoiding Interactive Mode
3. Prerequisites
4. Authentication
5. CLI Decision Tree
6. Command Quick Reference
7. Static Reference Data
8. Common Workflows
9. Private Networking
10. Error Handling
11. Framework Quick Start
12. JSON Output Mode
13. Quick Reference Card

Critical: Avoiding Interactive Mode

Railway CLI can enter interactive mode which will hang Claude Code. Always use flags:

railway link

railway link -p <project> -e <env>

railway init

railway init -n <name>

railway environment

railway environment <name>

railway down

railway down -y

railway redeploy

railway redeploy -y

railway up

railway up --detach

railway ssh

railway ssh -- <command>

Required flags:

-y

--detach

--json

-- <cmd>

Never use:

railway login

railway connect

railway shell

Prerequisites

# Verify installation
railway --version  # Expects: 3.x.x+

# Install options
npm i -g @railway/cli          # npm
brew install railway           # Homebrew
bash <(curl -fsSL cli.new)     # Shell script

Authentication

Token Types

RAILWAY_TOKEN

logs

up

RAILWAY_API_TOKEN

init

link

Critical:

railway logs

Quick Setup

# Set token for session
export RAILWAY_TOKEN="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

# Or inline from .env
RAILWAY_TOKEN=$(grep RAILWAY_TOKEN .env | cut -d= -f2) railway logs

# Verify authentication
railway whoami

Discovering Tokens

grep -i railway .env
grep -E '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}' .env

See REFERENCE.md for token creation and storage best practices.

CLI Decision Tree

Project Operations

├── Create project      → railway init -n <name>
├── Link to project     → railway link -p <project> -e <env>
├── List projects       → railway list
├── View status         → railway status
└── Open dashboard      → railway open

Deployment

├── Deploy (background) → railway up --detach
├── Redeploy            → railway redeploy -y
├── Remove deployment   → railway down -y
└── Deploy template     → railway deploy -t <template>

Services & Databases

├── Add PostgreSQL      → railway add -d postgres
├── Add Redis           → railway add -d redis
├── Add from repo       → railway add -r owner/repo
├── Run with vars       → railway run <command>
└── Link to service     → railway service <name>

Debugging

├── View logs           → railway logs
├── Build logs          → railway logs -b
├── SSH command         → railway ssh -- <command>
└── Check status        → railway status

Environment & Variables

├── Switch environment  → railway environment <name>
├── Create environment  → railway environment new -d <source>
├── Delete environment  → railway environment delete <name> -y
├── View variables      → railway variables
└── Set variable        → railway variables --set KEY=value

See REFERENCE.md for all commands with full flag details.

Command Quick Reference

Project Management

railway init

railway init -n myapp

railway link

railway link -p myproject -e production

railway list

railway list

railway status

railway status

railway unlink

railway unlink

Deployment

railway up

railway up --detach

railway redeploy

railway redeploy -y

railway down

railway down -y

railway logs

railway logs -d <id>

Services

railway add

railway add -d postgres

railway service

railway service api

railway run

railway run npm start

Debugging

railway logs

railway logs

railway logs -b

railway logs -b

railway ssh -- cmd

railway ssh -- ls -la

Static Reference Data

Regions

us-west2

us-east4-eqdc4a

europe-west4-drams3a

asia-southeast1-eqsg3a

Database Types

-d postgres

psql

-d mysql

mysql

-d redis

redis-cli

-d mongo

mongosh

Railway-Provided Variables

RAILWAY_PUBLIC_DOMAIN

RAILWAY_PRIVATE_DOMAIN

PORT

RAILWAY_ENVIRONMENT

Common Workflows

1. Deploy Application

railway init -n myapp                    # Create project
railway up --detach                      # Deploy (background)
railway logs                             # Check logs

2. Add Database

railway add -d postgres                  # Add PostgreSQL
railway run npm run migrate              # Run migrations

3. Configure Domain

railway domain                           # Generate Railway domain
railway domain api.myapp.com -p 3000     # Custom domain

4. Debug Failing Deployment

railway status                           # Check status
railway logs                             # View runtime logs
railway logs -b                          # View build logs
railway ssh -- ps aux                    # SSH command

5. CI/CD Deployment

export RAILWAY_TOKEN=${{ secrets.RAILWAY_TOKEN }}
railway up --detach -s api

See REFERENCE.md for GitHub Actions, GitLab CI, and CircleCI examples.

Private Networking

Services communicate via:

<service-name>.railway.internal

Example:

http://api.railway.internal:3000

Port Binding (Required)

Apps must listen on

::

// Node.js
app.listen(process.env.PORT, '::', () => console.log('Running'));

# Python
gunicorn --bind "[::]:${PORT:-8000}" app:app

See REFERENCE.md for library configurations and TCP proxy.

Error Handling

Common Errors

command not found: railway

Not logged in

RAILWAY_TOKEN

No project linked

railway link

Unauthorized

Deployment failed

railway logs -b

502 Error Debugging

# 1. Get PROJECT token (not account token)
grep -i railway .env

# 2. Set token and verify
export RAILWAY_TOKEN="<uuid>"
railway whoami

# 3. Check logs
railway logs

Common 502 causes: Missing dependencies, port binding issues, startup crashes.

See REFERENCE.md for comprehensive troubleshooting.

Framework Quick Start

Node.js

app.listen(process.env.PORT, '::', () => console.log('Running'));

Python

# Procfile
web: gunicorn --bind "[::]:${PORT:-8000}" app:app

Rails

// railway.json
{
  "deploy": {
    "startCommand": "bundle exec rails server -b :: -p $PORT"
  }
}

See REFERENCE.md for complete configuration options.

JSON Output Mode

railway status --json | jq '.services[].name'
railway logs --json | jq -r 'select(.level == "error") | .message'

Quick Reference Card

# Authentication
export RAILWAY_TOKEN="xxx"

# Project
railway init -n myapp
railway link -p myproject -e production
railway status

# Deploy
railway up --detach
railway redeploy -y
railway down -y

# Services
railway add -d postgres
railway run npm run migrate

# Debug
railway logs
railway logs -b
railway ssh -- ps aux

# Environment
railway environment staging
railway variables --set KEY=value

# Domain
railway domain api.example.com -p 3000

See REFERENCE.md for: Complete command documentation, advanced deployment patterns, volume management, environment variable strategies, networking deep dive, CI/CD integration, security best practices, troubleshooting, and config-as-code.