Environment Configuration

Read and edit Railway environment configuration using the CLI.

Prerequisites

Requires Railway CLI v4.27.3+. Check with:

bash

railway --version

If below 4.27.3, upgrade:

bash

railway upgrade

Quick Actions

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

bash

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:

bash

railway environment new <name>

Duplicate an existing environment:

bash

railway environment new staging --duplicate production

With service-specific variables:

bash

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

Switch Environment

Link a different environment to the current directory:

bash

railway environment <name>

Or by ID:

bash

railway environment <environment-id>

Get Context

JSON output — project/environment IDs and service list:

bash

railway status --json

Extract:

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

Plain output — linked service name:

bash

railway status

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

Resolve Service ID

Get service IDs from the environment config:

bash

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

Map service IDs to names via status:

bash

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:

bash

railway environment config --json

Response Structure

json

{
  "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:

bash

# 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.

bash

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

With a commit message:

bash

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

Examples

Set build command:

bash

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

Add variable:

bash

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

Delete variable:

bash

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

Delete service:

bash

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

Set replicas:

bash

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

Add shared variable:

bash

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

Batching Multiple Changes

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

bash

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:

bash

railway upgrade

Service Not Found

code

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

code

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

No Linked Project

code

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