---

name: managing-railway description: Railway platform CLI for service deployment, infrastructure management, and debugging. Use for creating services, managing deployments, configuring networking, and reviewing logs.

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

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

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

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

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

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

Services & Databases

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

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

Environment & Variables

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

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

2. Add Database

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

3. Configure Domain

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

4. Debug Failing Deployment

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

5. CI/CD Deployment

Copyexport 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:

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

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

See REFERENCE.md for library configurations and TCP proxy.

---

Error Handling

Common Errors

502 Error Debugging

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

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

Python

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

Rails

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

See REFERENCE.md for complete configuration options.

---

JSON Output Mode

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

---

Quick Reference Card

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