Environment Configuration

Query, stage, and apply configuration changes for Railway environments.

Shell Escaping

CRITICAL: When running GraphQL queries via bash, you MUST wrap in heredoc to prevent shell escaping issues:

bash

bash <<'SCRIPT'
${CLAUDE_PLUGIN_ROOT}/skills/lib/railway-api.sh 'query ...' '{"var": "value"}'
SCRIPT

Without the heredoc wrapper, multi-line commands break and exclamation marks in GraphQL non-null types get escaped, causing query failures.

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 railway-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
User says "apply changes", "commit changes", "deploy changes"
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

bash

railway status --json

Extract:

```
project.id
```
- for service lookup
```
environment.id
```
- for the mutations
```
service.id
```
- default service if user doesn't specify one

Resolve Service ID

If user specifies a service by name, query project services:

graphql

query projectServices($projectId: String!) {
  project(id: $projectId) {
    services {
      edges {
        node {
          id
          name
        }
      }
    }
  }
}

Match the service name (case-insensitive) to get the service ID.

Query Configuration

Fetch current environment configuration and staged changes.

graphql

query environmentConfig($environmentId: String!) {
  environment(id: $environmentId) {
    id
    config(decryptVariables: false)
    serviceInstances {
      edges {
        node {
          id
          serviceId
        }
      }
    }
  }
  environmentStagedChanges(environmentId: $environmentId) {
    id
    patch(decryptVariables: false)
  }
}

Example:

bash

bash <<'SCRIPT'
${CLAUDE_PLUGIN_ROOT}/skills/lib/railway-api.sh \
  'query envConfig($envId: String!) {
    environment(id: $envId) { id config(decryptVariables: false) }
    environmentStagedChanges(environmentId: $envId) { id patch(decryptVariables: false) }
  }' \
  '{"envId": "ENV_ID"}'
SCRIPT

Response Structure

The

config

field contains current configuration:

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": "..." } }
}

The

patch

field in

environmentStagedChanges

contains pending changes. The effective configuration is the base

config

merged with the staged

patch

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

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

Get Rendered Variables

The GraphQL queries above return 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_*)

Stage Changes

Stage configuration changes via the

environmentStageChanges

mutation. Use

merge: true

to automatically merge with existing staged changes.

graphql

mutation stageEnvironmentChanges(
  $environmentId: String!
  $input: EnvironmentConfig!
  $merge: Boolean
) {
  environmentStageChanges(
    environmentId: $environmentId
    input: $input
    merge: $merge
  ) {
    id
  }
}

Important: Always use variables (not inline input) because service IDs are UUIDs which can't be used as unquoted GraphQL object keys.

Example:

bash

bash <<'SCRIPT'
${CLAUDE_PLUGIN_ROOT}/skills/lib/railway-api.sh \
  'mutation stageChanges($environmentId: String!, $input: EnvironmentConfig!, $merge: Boolean) {
    environmentStageChanges(environmentId: $environmentId, input: $input, merge: $merge) { id }
  }' \
  '{"environmentId": "ENV_ID", "input": {"services": {"SERVICE_ID": {"build": {"buildCommand": "npm run build"}}}}, "merge": true}'
SCRIPT

Delete Service

Use

isDeleted: true

bash

bash <<'SCRIPT'
${CLAUDE_PLUGIN_ROOT}/skills/lib/railway-api.sh \
  'mutation stageChanges($environmentId: String!, $input: EnvironmentConfig!, $merge: Boolean) {
    environmentStageChanges(environmentId: $environmentId, input: $input, merge: $merge) { id }
  }' \
  '{"environmentId": "ENV_ID", "input": {"services": {"SERVICE_ID": {"isDeleted": true}}}, "merge": true}'
SCRIPT

Stage and Apply Immediately

For single changes that should deploy right away, use

environmentPatchCommit

to stage and apply in one call.

graphql

mutation environmentPatchCommit(
  $environmentId: String!
  $patch: EnvironmentConfig
  $commitMessage: String
) {
  environmentPatchCommit(
    environmentId: $environmentId
    patch: $patch
    commitMessage: $commitMessage
  )
}

Example:

bash

bash <<'SCRIPT'
${CLAUDE_PLUGIN_ROOT}/skills/lib/railway-api.sh \
  'mutation patchCommit($environmentId: String!, $patch: EnvironmentConfig, $commitMessage: String) {
    environmentPatchCommit(environmentId: $environmentId, patch: $patch, commitMessage: $commitMessage)
  }' \
  '{"environmentId": "ENV_ID", "patch": {"services": {"SERVICE_ID": {"variables": {"API_KEY": {"value": "secret"}}}}}, "commitMessage": "add API_KEY"}'
SCRIPT

When to use: Single change, no need to batch, user wants immediate deployment.

When NOT to use: Multiple related changes to batch, or user says "stage only" / "don't deploy yet".

Apply Staged Changes

Commit staged changes and trigger deployments.

Note: There is no

railway apply

CLI command. Use the mutation below or direct users to the web UI.

Apply Mutation

Mutation name:
environmentPatchCommitStaged

graphql

mutation environmentPatchCommitStaged(
  $environmentId: String!
  $message: String
  $skipDeploys: Boolean
) {
  environmentPatchCommitStaged(
    environmentId: $environmentId
    commitMessage: $message
    skipDeploys: $skipDeploys
  )
}

Example:

bash

bash <<'SCRIPT'
${CLAUDE_PLUGIN_ROOT}/skills/lib/railway-api.sh \
  'mutation commitStaged($environmentId: String!, $message: String) {
    environmentPatchCommitStaged(environmentId: $environmentId, commitMessage: $message)
  }' \
  '{"environmentId": "ENV_ID", "message": "add API_KEY variable"}'
SCRIPT

Parameters

Field	Type	Default	Description
`environmentId`	String!	-	Environment ID from status
`message`	String	null	Short description of changes
`skipDeploys`	Boolean	false	Skip deploys (only if user explicitly asks)

Commit Message

Keep very short - one sentence max. Examples:

"set build command to fix npm error"
"add API_KEY variable"
"increase replicas to 3"

Leave empty if no meaningful description.

Default Behavior

Always deploy unless user explicitly asks to skip. Only set

skipDeploys: true

if user says "apply without deploying", "commit but don't deploy", or "skip deploys".

Returns a workflow ID (string) on success.

Auto-Apply Behavior

By default, apply changes immediately.

Flow

Single change: Use

environmentPatchCommit

to stage and apply in one call.

Multiple changes or batching: Use

environmentStageChanges

with

merge: true

for each change, then

environmentPatchCommitStaged

to apply.

When NOT to Auto-Apply

User explicitly says "stage only", "don't deploy yet", or similar
User is making multiple related changes that should deploy together

When you don't auto-apply, tell the user:

Changes staged. Apply them at: https://railway.com/project/{projectId} Or ask me to apply them.

Get

projectId

from

railway status --json

→

project.id

Error Handling

Service Not Found

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

No Staged Changes

No patch to apply

There are no staged changes to commit. Stage changes first.

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 railway-service skill
View logs: Use railway-deployment skill
Add domains: Use railway-domain skill
Deploy local code: Use railway-deploy skill

railway-environment

NPX Install

Tags

SKILL.md Content

Environment Configuration

Shell Escaping

When to Use

Create Environment

Switch Environment

Get Context

Resolve Service ID

Query Configuration

Response Structure

Get Rendered Variables

Stage Changes

Delete Service

Stage and Apply Immediately

Apply Staged Changes

Apply Mutation

Parameters

Commit Message

Default Behavior

Auto-Apply Behavior

Flow

When NOT to Auto-Apply

Error Handling

Service Not Found

No Staged Changes

Invalid Configuration

No Permission

No Linked Project

Composability