railway-cli-setup

Railway CLI Setup for Cursor AI Agents

Version: 1.1
Date: February 28, 2026
Owner: AI Team

---

1. Purpose

This guide enables Cursor AI agents to deploy and manage Railway services. Railway is our platform for deploying backend services and applications.

---

2. Cursor MCP Integration (Preferred)

Cursor has a built-in Railway MCP integration that provides direct access to Railway operations.

Available MCP Tools

Tool	Description
user-Railway-check-railway-status	Check CLI installation and login status
user-Railway-list-projects	List all Railway projects
user-Railway-list-services	List services in linked project
user-Railway-deploy	Deploy from current directory
user-Railway-get-logs	Get build or deployment logs
user-Railway-list-variables	Show environment variables
user-Railway-set-variables	Set environment variables
user-Railway-generate-domain	Generate domain for service
user-Railway-create-environment	Create new environment
user-Railway-link-service	Link to a service
user-Railway-deploy-template	Deploy from template

---

3. CLI Installation

# Install via npm
npm install -g @railway/cli
 
# Or via Homebrew
brew install railway
 
# Verify installation
railway --version

---

4. Authentication

# Login (opens browser)
railway login
 
# Check login status
railway whoami

---

5. Common Operations

5.1 Link to Project

# Link current directory to a Railway project
railway link
 
# Or specify project
railway link --project "project-name"

5.2 Deploy

# Deploy from current directory
railway up
 
# Deploy with specific service
railway up --service "service-name"

5.3 View Logs

# Deployment logs
railway logs
 
# Build logs
railway logs --build
 
# Follow logs
railway logs -f

5.4 Environment Variables

# List variables
railway variables
 
# Set variable
railway variables set KEY=value
 
# Set multiple
railway variables set KEY1=value1 KEY2=value2

5.5 Pull platform env to .env.local

From apps/platform/:

# Pull production variables from linked Railway project/service
npm run pull-env
 
# Or target a specific env/service directly
node scripts/pull-railway-env.js --environment=production --service=web

Notes:

• npm run pull-env uses scripts/pull-railway-env.js
• scripts/pull-heroku-env.js is now a compatibility wrapper and redirects to Railway
• The script creates a timestamped .env.local backup before writing

5.6 Domains

# Generate domain
railway domain
 
# Custom domain
railway domain --custom mydomain.com

---

6. Cursor Agent Workflows

Deploy Service

1. Check status: user-Railway-check-railway-status
2. List projects: user-Railway-list-projects
3. Deploy: user-Railway-deploy (workspacePath: "/path/to/project")
4. Get logs: user-Railway-get-logs (logType: "deploy")

Set Environment Variables

user-Railway-set-variables
  workspacePath: "/path/to/project"
  variables: ["API_KEY=xxx", "DATABASE_URL=xxx"]
  service: "my-service" (optional)

---

7. Project Structure

Our Railway projects typically include:

• Production environment - Main deployment
• Staging environment - Testing deployments
• Preview environments - PR-specific deployments

---

8. API Reference

• Dashboard: https://railway.app/dashboard
• CLI Docs: https://docs.railway.app/reference/cli-api
• API Docs: https://docs.railway.app/reference/public-api

---

9. Troubleshooting

“Not linked to a project” error:

• Run railway link first
• Or use --project flag

Deployment fails:

• Check build logs: railway logs --build
• Verify environment variables are set
• Check Dockerfile/build configuration

“Authentication required” error:

• Run railway login
• Verify with railway whoami

---

10. Railway Public API token (Platform Deploy Status Dashboard)

The Platform app includes an internal deploy dashboard that queries Railway’s GraphQL API.

Required environment variable

Add this to apps/platform/.env.local:

RAILWAY_API_TOKEN=your_railway_api_token_here

Optional scoping variables:

# Limit dashboard to specific projects (comma-separated IDs)
# RAILWAY_PROJECT_IDS=proj_123,proj_456
 
# Preferred environment name when multiple environments exist
# RAILWAY_ENVIRONMENT_NAME=production

Where credentials should live

• Source of truth: Railway account/workspace token
• Store token in 1Password (Brainforge AI Team vault)
• Inject token via .env.local (never commit secrets)

How to verify

1. Start platform app: cd apps/platform && npm run dev
2. Open /internal/deploy-status
3. Confirm services, build statuses, and last deploy timestamps load

11. Version History

• v1.1 (February 28, 2026) — Added Railway Public API token setup for deploy status dashboard
• v1.0 (January 30, 2026) — Initial documentation