Scan to join WeChat groupRailway 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
- 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
# 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
# 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
| 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
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
| 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
# 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.