Railway CLI for IOTA SDK

Check Authentication

railway whoami

Context Management

Check current context:

railway status

List all projects with IDs:

railway list --json | jq '.'

Link project manually (create .railway/config.json):

mkdir -p .railway
cat > .railway/config.json << 'EOF'
{
  "projectId": "<your-project-id>"
}
EOF

Switch environment:

railway environment <environment>

Deployment

Deploy to specific environment and service:

railway up -s <service> -e <environment> --detach

Redeploy latest deployment:

railway redeploy -s <service> -e <environment> -y

Check deployment status:

railway status -s <service> -e <environment>

Monitoring

View deployment logs (real-time stream):

railway logs -s <service> -e <environment> --deployment

View build logs:

railway logs -s <service> -e <environment> --build

Get logs in JSON format (for parsing):

railway logs -s <service> -e <environment> --deployment --json

Filter logs for errors/panics:

# Text output with grep
railway logs -s iota-sdk -e staging --deployment 2>&1 | grep -i -E "(panic|error|fatal)"

# JSON output with jq (more reliable)
railway logs -s iota-sdk -e staging --deployment --json 2>&1 | \
  jq -r 'select(.message | test("panic|error|fatal"; "i")) | "\(.timestamp) \(.message)"'

Get context around errors:

# Get 30 lines after each match
railway logs -s iota-sdk -e staging --deployment 2>&1 | grep -A 30 "panic"

# Limit total output
railway logs -s iota-sdk -e staging --deployment 2>&1 | tail -100

Note: Railway enforces a rate limit of 500 logs/sec per replica. High-volume logging may result in dropped messages.

Variables

Get all variables for a service:

railway variables -s <service> -e <environment> --kv

Set a variable:

railway variables -s <service> -e <environment> --set "KEY=value"

Running Commands

Execute local command with remote environment variables:

railway run -s <service> -e <environment> -- <command>

Note: railway run executes locally, not on the remote service. Use for running local commands with staging/production environment variables.

Database Access

Connect to database shell:

railway connect db -e <environment>

Get database connection URL:

railway variables -s db -e <environment> --kv | grep DATABASE_PUBLIC_URL

SSH into service (requires active deployment):

railway ssh -s <service> -e <environment>

Common Operations for IOTA SDK

Analyzing Panics and Errors

Find recent panics with stack traces:

# Get panic with 30 lines of context (includes stack trace)
railway logs -s iota-sdk -e staging --deployment 2>&1 | grep -A 30 "panic"

# Find specific error patterns
railway logs -s iota-sdk -e staging --deployment --json 2>&1 | \
  jq -r 'select(.message | test("your-pattern"; "i")) | .message' | tail -50

Common error patterns for IOTA SDK:

• Translation errors: "message .* not found in language"
• Database errors: "pq:|postgres:|connection|timeout"
• HTTP panics: "http: panic serving"
• Multi-tenant errors: "tenant_id|organization_id|forbidden"
• Permission errors: "permission denied|insufficient permissions"

Running Migrations on Staging

Get database credentials and run migrations locally:

# Get the public database URL
railway variables -s db -e staging --kv | grep DATABASE_PUBLIC_URL
# Example output: DATABASE_PUBLIC_URL=postgresql://postgres:PASSWORD@HOST:PORT/railway

# Extract connection details from the URL and export
export DB_HOST=<host-from-url>          # Example: shuttle.proxy.rlwy.net
export DB_PORT=<port-from-url>          # Example: 31150
export DB_NAME=<database-from-url>      # Example: railway
export DB_USER=<user-from-url>          # Example: postgres
export DB_PASSWORD=<password-from-url>

# Check migration status
make db migrate status

# Run pending migrations
make db migrate up

# Rollback if needed
make db migrate down

Deploying New Version

# 1. Verify current status
railway status -s iota-sdk -e staging

# 2. Deploy new version
railway up -s iota-sdk -e staging --detach

# 3. Monitor deployment logs
railway logs -s iota-sdk -e staging --deployment

# 4. Verify deployment success
railway status -s iota-sdk -e staging

# 5. Check for errors
railway logs -s iota-sdk -e staging --deployment 2>&1 | grep -i error | tail -20

Environment Variable Management

# List all environment variables
railway variables -s iota-sdk -e staging --kv

# Update application config
railway variables -s iota-sdk -e staging --set "LOG_LEVEL=debug"

# Update database connection (example)
railway variables -s iota-sdk -e staging --set "DB_HOST=new-host"

# Trigger restart after variable changes
railway redeploy -s iota-sdk -e staging -y

Database Backup

# Get database URL
DB_URL=$(railway variables -s db -e staging --kv | grep DATABASE_PUBLIC_URL | cut -d'=' -f2)

# Create backup
pg_dump "$DB_URL" > backup_$(date +%Y%m%d_%H%M%S).sql

# Or with compression
pg_dump "$DB_URL" | gzip > backup_$(date +%Y%m%d_%H%M%S).sql.gz

IOTA SDK Project Structure

Environment Names:

• staging - Staging environment
• production - Production environment

Service Names (adjust based on actual setup):

• iota-sdk - Main Go application
• db - PostgreSQL database

Example with actual service names:

# Deploy to staging
railway up -s iota-sdk -e staging --detach

# View logs
railway logs -s iota-sdk -e staging --deployment

# Check database
railway connect db -e staging

Troubleshooting

"Project not found": Create .railway/config.json with projectId

"No deployment found": Service has no active deployment in that environment

SSH connection fails: Ensure deployment is running, use railway logs to check status

Logs not showing: Check service name and environment are correct

Variable not updating: Redeploy service after setting variables

Production Safety

Always specify -e staging explicitly when working with staging to avoid accidentally affecting production.

Before Running Production Operations

1. Double-check the environment flag (-e production)
2. Verify current context with railway status
3. Test on staging first
4. Have a rollback plan ready
5. Announce deployment to team
6. Monitor logs during deployment

Production Deployment Checklist

• Code changes reviewed and approved
• Tests passing in CI/CD
• Staging deployment successful
• Database migrations tested on staging
• Rollback plan prepared
• Team notified of deployment
• Monitoring dashboard ready
• Environment flag verified (-e production)

Emergency Rollback

# 1. Check recent deployments
railway status -s iota-sdk -e production

# 2. Redeploy previous version (if using git tags/branches)
git checkout <previous-version>
railway up -s iota-sdk -e production --detach

# 3. Or use Railway dashboard to rollback
# Visit Railway dashboard → Service → Deployments → Rollback

Quick Reference

# Authentication
railway whoami
railway status

# Deployment
railway up -s iota-sdk -e staging --detach
railway redeploy -s iota-sdk -e staging -y

# Logs
railway logs -s iota-sdk -e staging --deployment
railway logs -s iota-sdk -e staging --deployment | grep -i error

# Variables
railway variables -s iota-sdk -e staging --kv
railway variables -s iota-sdk -e staging --set "KEY=value"

# Database
railway connect db -e staging
railway variables -s db -e staging --kv | grep DATABASE_PUBLIC_URL

# SSH
railway ssh -s iota-sdk -e staging

Common Workflows

Debug Production Issue

# 1. View recent logs
railway logs -s iota-sdk -e production --deployment | tail -100

# 2. Search for errors
railway logs -s iota-sdk -e production --deployment | grep -i error -A 10

# 3. Check database connection
railway variables -s iota-sdk -e production --kv | grep DB_

# 4. SSH into service if needed
railway ssh -s iota-sdk -e production

Update Environment Configuration

# 1. Get current variables
railway variables -s iota-sdk -e staging --kv > current_vars.txt

# 2. Update variables
railway variables -s iota-sdk -e staging --set "NEW_FEATURE_FLAG=true"
railway variables -s iota-sdk -e staging --set "LOG_LEVEL=info"

# 3. Redeploy to apply changes
railway redeploy -s iota-sdk -e staging -y

# 4. Verify changes
railway logs -s iota-sdk -e staging --deployment | head -50

Monitor Deployment

# Terminal 1: Watch deployment status
watch -n 5 'railway status -s iota-sdk -e staging'

# Terminal 2: Stream logs
railway logs -s iota-sdk -e staging --deployment

# Terminal 3: Check for errors
watch -n 10 'railway logs -s iota-sdk -e staging --deployment | grep -i error | tail -20'