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 in .env, or user mentions Railway.

•Overview
•Critical: Avoiding Interactive Mode
•Prerequisites
•Authentication
•CLI Decision Tree
•Command Quick Reference
•Static Reference Data
•Common Workflows
•Private Networking
•Error Handling
•Framework Quick Start
•JSON Output Mode
•Quick Reference Card

Critical: Avoiding Interactive Mode

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

Command	WRONG	CORRECT
Link project	`railway link`	`railway link -p <project> -e <env>`
Create project	`railway init`	`railway init -n <name>`
Switch env	`railway environment`	`railway environment <name>`
Remove deploy	`railway down`	`railway down -y`
Redeploy	`railway redeploy`	`railway redeploy -y`
Deploy	`railway up`	`railway up --detach`
SSH	`railway ssh`	`railway ssh -- <command>`

Required flags: -y (skip prompts), --detach (background), explicit names, --json (parsing), -- <cmd> (SSH).

Never use: railway login, railway connect (without service), railway shell, commands without explicit params.

Prerequisites

bash

# 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

Token Type	Env Variable	Scope
Project Token	`RAILWAY_TOKEN`	Single environment (for `logs`, `up`)
Account Token	`RAILWAY_API_TOKEN`	All projects (for `init`, `link`)

Critical: railway logs requires a Project Token, not an account token.

Quick Setup

bash

# 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

bash

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

code

├── 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

code

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

Services & Databases

code

├── 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

code

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

Environment & Variables

code

├── 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

Command	Example
`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

Command	Example
`railway up`	`railway up --detach`
`railway redeploy`	`railway redeploy -y`
`railway down`	`railway down -y`
`railway logs`	`railway logs -d <id>`

Services

Command	Example
`railway add`	`railway add -d postgres`
`railway service`	`railway service api`
`railway run`	`railway run npm start`

Debugging

Command	Example
`railway logs`	`railway logs`
`railway logs -b`	`railway logs -b`
`railway ssh -- cmd`	`railway ssh -- ls -la`

Static Reference Data

Regions

Code	Location
`us-west2`	California, USA
`us-east4-eqdc4a`	Virginia, USA
`europe-west4-drams3a`	Amsterdam, Netherlands
`asia-southeast1-eqsg3a`	Singapore

Database Types

Type	Flag	Shell
PostgreSQL	`-d postgres`	`psql`
MySQL	`-d mysql`	`mysql`
Redis	`-d redis`	`redis-cli`
MongoDB	`-d mongo`	`mongosh`

Railway-Provided Variables

Variable	Description
`RAILWAY_PUBLIC_DOMAIN`	Public domain
`RAILWAY_PRIVATE_DOMAIN`	Private domain (.railway.internal)
`PORT`	Port to listen on
`RAILWAY_ENVIRONMENT`	Environment name

Common Workflows

1. Deploy Application

bash

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

2. Add Database

bash

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

3. Configure Domain

bash

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

4. Debug Failing Deployment

bash

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

bash

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 :: for IPv4/IPv6:

javascript

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

bash

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

See REFERENCE.md for library configurations and TCP proxy.

Error Handling

Common Errors

Error	Resolution
`command not found: railway`	Install via npm/brew
`Not logged in`	Set `RAILWAY_TOKEN`
`No project linked`	Run `railway link`
`Unauthorized`	Check token, re-authenticate
`Deployment failed`	Check `railway logs -b`

502 Error Debugging

bash

# 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

javascript

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

Python

bash

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

Rails

json

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

See REFERENCE.md for complete configuration options.

JSON Output Mode

bash

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

Quick Reference Card

bash

# 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.

Railway CLI Skill

Overview

Table of Contents

Critical: Avoiding Interactive Mode

Prerequisites

Authentication

Token Types

Quick Setup

Discovering Tokens

CLI Decision Tree

Project Operations

Deployment

Services & Databases

Debugging

Environment & Variables

Command Quick Reference

Project Management

Deployment

Services

Debugging

Static Reference Data

Regions

Database Types

Railway-Provided Variables

Common Workflows

1. Deploy Application

2. Add Database

3. Configure Domain

4. Debug Failing Deployment

5. CI/CD Deployment

Private Networking

Port Binding (Required)

Error Handling

Common Errors

502 Error Debugging

Framework Quick Start

Node.js

Python

Rails

JSON Output Mode

Quick Reference Card