Railway CLI Skill

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.

---

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:

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

# 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

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

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

Deployment

Services

Debugging

---

Static Reference Data

Regions

Database Types

Railway-Provided Variables

---

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

// 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

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.