The-Utopia-Studio/environment

Environment Configuration

Read and edit Railway environment configuration using the CLI.

Prerequisites

Requires Railway CLI v4.27.3+. Check with:

railway --version

If below 4.27.3, upgrade:

railway upgrade

Quick Actions

When user asks "what's the config" or "show configuration":

railway environment config --json

Present: source (repo/image), build settings, deploy settings, variables per service.

When user asks "what variables" or "show env vars":

Same command — railway environment config --json includes variables per service and shared variables.

For rendered (resolved) variable values: railway variables --json

When to Use

• User wants to create a new environment
• User wants to duplicate an environment (e.g., "copy production to staging")
• User wants to switch to a different environment
• User asks about current build/deploy settings, variables, replicas, health checks, domains
• User asks to change service source (Docker image, branch, commit, root directory)
• User wants to connect a service to a GitHub repo
• User wants to deploy from a GitHub repo (create empty service first via new skill, then use this)
• User asks to change build or start command
• User wants to add/update/delete environment variables
• User wants to change replica count or configure health checks
• User asks to delete a service, volume, or bucket
• Auto-fixing build errors detected in logs

Create Environment

Create a new environment in the linked project:

railway environment new <name>

Duplicate an existing environment:

railway environment new staging --duplicate production

With service-specific variables:

railway environment new staging --duplicate production --service-variable api PORT=3001

Switch Environment

Link a different environment to the current directory:

railway environment <name>

Or by ID:

railway environment <environment-id>

Get Context

JSON output — project/environment IDs and service list:

railway status --json

Extract:

• project.id — project ID
• environment.id — environment ID

Plain output — linked service name:

railway status

Shows Service: <name> line with the currently linked service.

Resolve Service ID

Get service IDs from the environment config:

railway environment config --json | jq '.services | keys'

Map service IDs to names via status:

railway status --json

The project.services array contains { id, name } for each service. Match against the service keys from environment config.

Read Configuration

Fetch current environment configuration:

railway environment config --json

Response Structure

{
  "services": {
    "<serviceId>": {
      "source": { "repo": "...", "branch": "main" },
      "build": { "buildCommand": "npm run build", "builder": "NIXPACKS" },
      "deploy": {
        "startCommand": "npm start",
        "multiRegionConfig": { "us-west2": { "numReplicas": 1 } }
      },
      "variables": { "NODE_ENV": { "value": "production" } },
      "networking": { "serviceDomains": {}, "customDomains": {} }
    }
  },
  "sharedVariables": { "DATABASE_URL": { "value": "..." } }
}

For complete field reference, see reference/environment-config.md.

For variable syntax and service wiring patterns, see reference/variables.md.

Get Rendered Variables

environment config returns unrendered variables — template syntax like ${{shared.DOMAIN}} is preserved. This is correct for management/editing.

To see rendered (resolved) values as they appear at runtime:

# Current linked service
railway variables --json

# Specific service
railway variables --service <service-name> --json

When to use:

• Debugging connection issues (see actual URLs/ports)
• Verifying variable resolution is correct
• Viewing Railway-injected values (RAILWAY_*)

Edit Configuration

Pass a JSON patch to railway environment edit to apply changes. The patch is merged with existing config and committed immediately, triggering deploys.

railway environment edit --json <<< '<json-patch>'

With a commit message:

railway environment edit -m "description of change" --json <<< '<json-patch>'

Examples

Set build command:

railway environment edit --json <<< '{"services":{"SERVICE_ID":{"build":{"buildCommand":"npm run build"}}}}'

Add variable:

railway environment edit -m "add API_KEY" --json <<< '{"services":{"SERVICE_ID":{"variables":{"API_KEY":{"value":"secret"}}}}}'

Delete variable:

railway environment edit --json <<< '{"services":{"SERVICE_ID":{"variables":{"OLD_VAR":null}}}}'

Delete service:

railway environment edit --json <<< '{"services":{"SERVICE_ID":{"isDeleted":true}}}'

Set replicas:

railway environment edit --json <<< '{"services":{"SERVICE_ID":{"deploy":{"multiRegionConfig":{"us-west2":{"numReplicas":3}}}}}}'

Add shared variable:

railway environment edit --json <<< '{"sharedVariables":{"DATABASE_URL":{"value":"postgres://..."}}}'

Batching Multiple Changes

Include multiple fields in a single patch to apply them atomically:

railway environment edit -m "configure build, start, and env" --json <<< '{"services":{"SERVICE_ID":{"build":{"buildCommand":"npm run build"},"deploy":{"startCommand":"npm start"},"variables":{"NODE_ENV":{"value":"production"}}}}}'

Error Handling

Command Not Found

If railway environment edit is not recognized, upgrade the CLI:

railway upgrade

Service Not Found

Service "foo" not found in project. Available services: api, web, worker

Invalid Configuration

Common issues:

• buildCommand and startCommand cannot be identical
• buildCommand only valid with NIXPACKS builder
• dockerfilePath only valid with DOCKERFILE builder

No Permission

You don't have permission to modify this environment. Check your Railway role.

No Linked Project

No project linked. Run `railway link` to link a project.

Composability

• Create service: Use service skill
• View logs: Use deployment skill
• Add domains: Use domain skill
• Deploy local code: Use deploy skill