Query, stage, and apply configuration changes for Railway environments. Use for ANY variable or env var operations, service configuration (source, build settings, deploy settings), lifecycle (delete service), and applying changes. Prefer over railway-status skill for any configuration or variable queries.
npxskills add davila7/claude-code-templates--skill railway-environmentLoading…
Query, stage, and apply configuration changes for Railway environments.
CRITICAL: When running GraphQL queries via bash, you MUST wrap in heredoc to prevent shell escaping issues:
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.
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
Link a different environment to the current directory:
railway environment <name>
Or by ID:
railway environment <environment-id>
railway status --json
Extract:
project.id - for service lookupenvironment.id - for the mutationsservice.id - default service if user doesn't specify oneIf user specifies a service by name, query project services:
query projectServices($projectId: String!) {
project(id: $projectId) {
services {
edges {
node {
id
name
}
}
}
}
}
Match the service name (case-insensitive) to get the service ID.
Fetch current environment configuration and staged changes.
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 <<'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
The config field contains current configuration:
{
"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.
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:
# Current linked service
railway variables --json
# Specific service
railway variables --service <service-name> --json
When to use:
Stage configuration changes via the environmentStageChanges mutation. Use merge: true to automatically merge with existing staged changes.
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 <<'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
Use isDeleted: true:
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
For single changes that should deploy right away, use environmentPatchCommit to stage and apply in one call.
mutation environmentPatchCommit(
$environmentId: String!
$patch: EnvironmentConfig
$commitMessage: String
) {
environmentPatchCommit(
environmentId: $environmentId
patch: $patch
commitMessage: $commitMessage
)
}
Example:
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".
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.
Mutation name: environmentPatchCommitStaged
mutation environmentPatchCommitStaged(
$environmentId: String!
$message: String
$skipDeploys: Boolean
) {
environmentPatchCommitStaged(
environmentId: $environmentId
commitMessage: $message
skipDeploys: $skipDeploys
)
}
Example:
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
| 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) |
Keep very short - one sentence max. Examples:
Leave empty if no meaningful description.
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.
By default, apply changes immediately.
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 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
Service "foo" not found in project. Available services: api, web, worker
No patch to apply
There are no staged changes to commit. Stage changes first.
Common issues:
buildCommand and startCommand cannot be identicalbuildCommand only valid with NIXPACKS builderdockerfilePath only valid with DOCKERFILE builderYou don't have permission to modify this environment. Check your Railway role.
No project linked. Run `railway link` to link a project.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).