--- 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](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](#overview) 2. [Critical: Avoiding Interactive Mode](#critical-avoiding-interactive-mode) 3. [Prerequisites](#prerequisites) 4. [Authentication](#authentication) 5. [CLI Decision Tree](#cli-decision-tree) 6. [Command Quick Reference](#command-quick-reference) 7. [Static Reference Data](#static-reference-data) 8. [Common Workflows](#common-workflows) 9. [Private Networking](#private-networking) 10. [Error Handling](#error-handling) 11. [Framework Quick Start](#framework-quick-start) 12. [JSON Output Mode](#json-output-mode) 13. [Quick Reference Card](#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 -e ` | | Create project | `railway init` | `railway init -n ` | | Switch env | `railway environment` | `railway environment ` | | Remove deploy | `railway down` | `railway down -y` | | Redeploy | `railway redeploy` | `railway redeploy -y` | | Deploy | `railway up` | `railway up --detach` | | SSH | `railway ssh` | `railway ssh -- ` | **Required flags**: `-y` (skip prompts), `--detach` (background), explicit names, `--json` (parsing), `-- ` (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](REFERENCE.md#token-management) for token creation and storage best practices. --- ## CLI Decision Tree ### Project Operations ``` ├── Create project → railway init -n ├── Link to project → railway link -p -e ├── 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