railway

Railway

Three modes. Pick based on intent:

========================================

Deploy mode — deploy or update a Railway service

Deploy to Railway with pre-flight checks, build monitoring, health verification, and post-deploy log review.

Instructions

Follow these steps exactly in order. Do NOT skip the user confirmation gate in Step 2.

---

Step 0: Prerequisites

Run these checks in order. Stop at the first failure and guide the user.

1. CLI installed?

railway --version

• If the command fails (not found): tell the user to install with npm install -g @railway/cli or brew install railway

2. Version check (minimum 4.27.3):

railway --version

• If below 4.27.3: tell the user to update with npm update -g @railway/cli

3. Authenticated?

railway whoami --json

• If the command fails: tell the user to run railway login

4. Project linked?

railway status --json

• If the command fails: tell the user to run railway link to select a project

---

Step 1: Pre-Deploy Check

Gather context about what's about to be deployed.

Railway context:

railway status --json

Parse: project name, linked service, current environment.

Git context:

git log -1 --oneline
git status --porcelain

Warn if uncommitted changes exist. Railway deploys the working directory contents — uncommitted changes WILL be included in the deploy but NOT in git history, which causes drift.

Present a pre-deploy summary:

Deploy Summary
═══════════════════════════════════════════════════════
  Project:      [name]
  Service:      [service]
  Environment:  [env]
  Branch:       [git branch]
  Commit:       [short hash] [message]
  Uncommitted:  [Y/N — warn if Y]
═══════════════════════════════════════════════════════

Step 2: User Confirmation Gate

Ask the user: "Ready to deploy? (y/n)"

Do NOT proceed until the user explicitly confirms. If they say no, stop and ask what they'd like to change.

Step 3: Deploy

CI mode (streams build logs inline):

railway up --ci -m "<descriptive deploy message>"

Always use -m with a meaningful message. Derive it from:

• The most recent commit message, OR
• What the user described as the purpose of this deploy

If the project uses auto-deploy on git push: Tell the user: "This project appears to use auto-deploy. Push your changes with git push and I'll monitor the deployment."

Then monitor:

railway deployment list --limit 1 --json

Poll until the deployment status changes from BUILDING to SUCCESS or FAILED.

Step 4: Health Check

After the build completes and the deployment is live:

Check public domains:

railway status --json

Parse the JSON output to extract domain URLs.

For each domain:

curl -s -o /dev/null -w "%{http_code}" https://<domain>

• 200-299 → healthy
• 301-399 → redirect (follow it and check final destination)
• 4xx/5xx → unhealthy, flag immediately
• Connection timeout → service may still be starting, wait 10s and retry once

If no public domain exists, ask the user: "No public domain found. Do you have a health endpoint I should check?"

Step 5: Post-Deploy Log Review

railway logs --lines 50 --json

Check for:

• Any @level:error entries since deploy
• Startup failures or crash loops
• Connection errors to databases or external services
• OOM or memory warnings

Step 6: Deploy Report

Present a final summary:

Deploy Report
═══════════════════════════════════════════════════════
  Status:       [SUCCESS / FAILED / DEGRADED]
  Service:      [service name]
  Environment:  [environment]
  Commit:       [hash] [message]
  Deploy msg:   [the -m message used]
  Build:        [duration if available]
  Health:       [HTTP status for each domain]
  Errors:       [count of error-level logs since deploy]
═══════════════════════════════════════════════════════

If the deploy failed or health checks are unhealthy:

• Show the relevant error logs
• Suggest checking railway logs --filter "@level:error" --lines 100
• Offer to roll back: railway down -y stops the current deployment (service stays, deploy stops)
• Note: railway down stops the deployment but does NOT delete the service

$ARGUMENTS

========================================

Logs mode — view, filter, or stream service logs

View and filter Railway service logs. Supports JSON output, level filtering, time ranges, and pattern matching.

Instructions

Follow these steps exactly in order.

---

Step 0: Prerequisites

Run these checks in order. Stop at the first failure and guide the user.

1. CLI installed?

railway --version

• If the command fails (not found): tell the user to install with npm install -g @railway/cli or brew install railway

2. Version check (minimum 4.27.3):

railway --version

• If below 4.27.3: tell the user to update with npm update -g @railway/cli

3. Authenticated?

railway whoami --json

• If the command fails: tell the user to run railway login

4. Project linked?

railway status --json

• If the command fails: tell the user to run railway link to select a project

---

Step 1: Fetch Logs

Default (last 100 lines):

railway logs --lines 100 --json

Specific service:

railway logs --service <name> --lines 100 --json

With level filter:

railway logs --filter "@level:error" --lines 100 --json

With time range (relative):

railway logs --lines 100 --json  # then filter by timestamp

Step 2: Filter & Analyze

Parse the JSON output and apply any user-requested filters.

Built-in filters:

• @level:error — errors only
• @level:warn — warnings only
• @level:info — info messages only

Pattern-based filtering:

railway logs --lines 200 --json

Parse the JSON output yourself to find entries whose message field matches the user's search pattern (case-insensitive). Do NOT pipe through jq -- read and filter the JSON directly.

Common Investigations

Recent errors:

railway logs --filter "@level:error" --lines 100 --json

Deployment startup issues:

railway logs --lines 50 --service <name> --json

Memory / OOM issues:

railway logs --lines 200 --json

Parse the JSON output to find entries with messages matching: memory, oom, killed (case-insensitive).

Connection issues:

railway logs --lines 200 --json

Parse the JSON output to find entries with messages matching: ECONNREFUSED, timeout, ETIMEDOUT (case-insensitive).

Crash loops:

railway logs --lines 200 --json

Parse the JSON output to find entries with messages matching: exit, crash, restart, signal (case-insensitive).

Step 3: Present Results

Format log output clearly:

• Group by severity if mixed levels
• Highlight errors and warnings
• Show timestamps in human-readable format
• If logs are empty or the service has no recent activity, say so
• Suggest next steps based on what the logs show

Output Modes

JSON (default — best for parsing):

railway logs --lines 100 --json

Save to file:

railway logs --lines 500 --json

If the user wants logs saved to a file, write the output to /tmp/railway-logs.json using the Write tool.

Structured view:

railway logs --lines 100 --json

Parse the JSON output and present each entry as a structured record with timestamp, level, and message fields. Do NOT pipe through jq.

$ARGUMENTS

========================================

Status mode — project overview: services, deployments, environments, metrics

Quick dashboard for your Railway project. Shows project info, services, recent deployments, environments, and resource metrics at a glance.

Instructions

Follow these steps exactly in order.

---

Step 0: Prerequisites

Run these checks in order. Stop at the first failure and guide the user.

1. CLI installed?

railway --version

• If the command fails (not found): tell the user to install with npm install -g @railway/cli or brew install railway

2. Version check (minimum 4.27.3):

railway --version

• If below 4.27.3: tell the user to update with npm update -g @railway/cli

3. Authenticated?

railway whoami --json

• If the command fails: tell the user to run railway login

4. Project linked?

railway status --json

• If the command fails: tell the user to run railway link to select a project

---

Step 1: Project & Service Overview

railway status --json

Parse and present: project name, project ID, current environment, linked service.

Step 2: All Services

railway service list --json

List all services with their current deployment status.

Step 3: Recent Deployments

railway deployment list --limit 5 --json

Show the 5 most recent deployments: status, service, trigger, timestamp, commit.

Step 4: Environments

railway environment list --json

List all environments (production, staging, PR environments, etc.).

Step 5: Environment Variables

railway variables list --json

List variable names only — never display values. Note any common variables that appear unset.

Step 6: Resource Metrics (if available)

Attempt to query Railway's GraphQL API for CPU and memory metrics of active services.

First, read the Railway config to get the auth token:

cat ~/.railway/config.json

Parse the JSON output to extract the value at .user.token. If the file doesn't exist or the token field is missing, skip this step and note: "GraphQL metrics unavailable -- token not found in ~/.railway/config.json"

Next, get the project ID:

railway status --json

Parse the JSON output to extract the projectId value.

Then, query the Railway GraphQL API using the extracted token and project ID (substitute the actual values into the command):

curl -s https://backboard.railway.com/graphql/v2 -H "Authorization: Bearer <TOKEN>" -H "Content-Type: application/json" -d "{\"query\": \"query { project(id: \\\"<PROJECT_ID>\\\") { services { edges { node { id name serviceInstances { edges { node { latestDeployment { id status } } } } } } } } }\"}"

Parse the JSON response to extract service names, deployment IDs, and statuses.

If the token is missing or any query fails, skip this step and note: "GraphQL metrics unavailable -- token not found in ~/.railway/config.json"

Step 7: Present Dashboard

Format all output as a clean summary:

Railway Dashboard
═══════════════════════════════════════════════════════
  Project:      [name] ([id])
  Environment:  [current env]
  Linked:       [service name]
═══════════════════════════════════════════════════════

Services
┌──────────────────┬───────────┬─────────────────────┐
│ Service          │ Status    │ Last Deploy         │
├──────────────────┼───────────┼─────────────────────┤
│ ...              │ ...       │ ...                 │
└──────────────────┴───────────┴─────────────────────┘

Recent Deployments
┌──────────────────┬───────────┬──────────┬──────────┐
│ Service          │ Status    │ Trigger  │ When     │
├──────────────────┼───────────┼──────────┼──────────┤
│ ...              │ ...       │ ...      │ ...      │
└──────────────────┴───────────┴──────────┴──────────┘

Environments: [list]
Variables: [count] variables set (names only shown above)
Metrics: [CPU/memory if available, or "unavailable"]

========================================

Migration

Consolidated from legacy claudefather skills. Pick the mode based on intent.