use-railway

Name: use-railway
Author: railwayapp

299stars34forks

How to install use-railway?

railwayapp/railway-skills/use-railway

$npx -y skills add railwayapp/railway-skills --skill use-railway

Installs into the current project.

Summary

Operate Railway infrastructure: sign up for or sign in to a Railway account, create projects, provision services and databases, manage object storage buckets, deploy code, configure infrastructure as code, environments and variables, manage domains, troubleshoot failures, check s

Files · 1

View on GitHub

SKILL.md

1	# Use Railway
2
3	## Railway resource model
4
5	Railway organizes infrastructure in a hierarchy:
6
7	- Workspace is the billing and team scope. A user belongs to one or more workspaces.
8	- Project is a collection of services under one workspace. It maps to one deployable unit of work.
9	- Environment is an isolated configuration plane inside a project (for example, `production`, `staging`). Each environment has its own variables, config, and deployment history.
10	- Service is a single deployable unit inside a project. It can be an app from a repo, a Docker image, or a managed database.
11	- Bucket is an S3-compatible object storage resource inside a project. Buckets are created at the project level and deployed to environments. Each bucket has credentials (endpoint, access key, secret key) for S3-compatible access.
12	- Deployment is a point-in-time release of a service in an environment. It has build logs, runtime logs, and a status lifecycle.
13
14	Most CLI commands operate on the linked project/environment/service context. Use `railway status --json` to see the context, and `--project`, `--environment`, `--service` flags to override.
15
16	## Tool routing
17
18	Railway has three agent-facing operation paths. Choose the path that matches the job:
19
20	- Railway CLI (`railway`): workflows that depend on local machine state such as current working directory deploys, `railway up`, `railway run`, SSH, database analysis scripts, local linking, interactive setup, or exact command output.
21	- Remote MCP (`https://mcp.railway.com`): default plugin MCP path for account/project/service discovery, deployment state, bounded logs, feature flags, simple redeploys, simple project creation, or complex Railway workflows that can be handed to `railway-agent`. Remote MCP uses Railway OAuth and does not depend on local CLI state.
22	- GraphQL: operations that neither MCP nor CLI exposes, or when a reference gives a specific GraphQL fallback.
23
24	If multiple paths are available, choose the one that preserves the needed context. The CLI fits workflows that need the current repo, local credentials, SSH, database scripts, or exact command output. Remote MCP fits OAuth-scoped platform operations that do not need local files or CLI state.
25
26	Optional: if the current agent already has a user-installed local CLI MCP (`railway mcp`) configured, it can be used for CLI-backed platform operations not yet exposed by remote MCP. Published plugin configs do not install or launch local CLI MCP.
27
28	Use `scripts/railway-api.sh` for GraphQL only when neither MCP nor CLI exposes the operation, or when a reference gives a specific GraphQL fallback.
29
30	## Parsing Railway URLs
31
32	Users often paste Railway dashboard URLs. Extract IDs before doing anything else:
33
34	```
35	https://railway.com/project/<PROJECT_ID>/service/<SERVICE_ID>?environmentId=<ENV_ID>
36	https://railway.com/project/<PROJECT_ID>/service/<SERVICE_ID>
37	```
38
39	The URL always contains `projectId` and `serviceId`. It may contain `environmentId` as a query parameter. If the environment ID is missing and the user specifies an environment by name (e.g., "production"), resolve it:
40
41	```bash
42	scripts/railway-api.sh \
43	'query getProject($id: String!) {
44	project(id: $id) {
45	environments { edges { node { id name } } }
46	}
47	}' \
48	'{"id": "<PROJECT_ID>"}'
49	```
50
51	Match the environment name (case-insensitive) to get the `environmentId`.
52
53	Prefer passing explicit IDs to CLI commands (`--project`, `--environment`, `--service`) and scripts (`--project-id`, `--environment-id`, `--service-id`) instead of running `railway link`. This avoids modifying global state and is faster.
54
55	## Intent-based routing
56
57	Route by user intent before running preflight checks. The preflight ceremony below is for diagnostic and configuration work — it adds friction when the user just wants to ship something or sign up.

People who liked this also viewed

6 picks

Type

use-railway

299stars34forks

View on GitHub

How to install use-railway?

railwayapp/railway-skills/use-railway

$npx -y skills add railwayapp/railway-skills --skill use-railway

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Use Railway
2
3	## Railway resource model
4
5	Railway organizes infrastructure in a hierarchy:
6
7	- Workspace is the billing and team scope. A user belongs to one or more workspaces.
8	- Project is a collection of services under one workspace. It maps to one deployable unit of work.
9	- Environment is an isolated configuration plane inside a project (for example, `production`, `staging`). Each environment has its own variables, config, and deployment history.
10	- Service is a single deployable unit inside a project. It can be an app from a repo, a Docker image, or a managed database.
11	- Bucket is an S3-compatible object storage resource inside a project. Buckets are created at the project level and deployed to environments. Each bucket has credentials (endpoint, access key, secret key) for S3-compatible access.
12	- Deployment is a point-in-time release of a service in an environment. It has build logs, runtime logs, and a status lifecycle.
13
14	Most CLI commands operate on the linked project/environment/service context. Use `railway status --json` to see the context, and `--project`, `--environment`, `--service` flags to override.
15
16	## Tool routing
17
18	Railway has three agent-facing operation paths. Choose the path that matches the job:
19
20	- Railway CLI (`railway`): workflows that depend on local machine state such as current working directory deploys, `railway up`, `railway run`, SSH, database analysis scripts, local linking, interactive setup, or exact command output.
21	- Remote MCP (`https://mcp.railway.com`): default plugin MCP path for account/project/service discovery, deployment state, bounded logs, feature flags, simple redeploys, simple project creation, or complex Railway workflows that can be handed to `railway-agent`. Remote MCP uses Railway OAuth and does not depend on local CLI state.
22	- GraphQL: operations that neither MCP nor CLI exposes, or when a reference gives a specific GraphQL fallback.
23
24	If multiple paths are available, choose the one that preserves the needed context. The CLI fits workflows that need the current repo, local credentials, SSH, database scripts, or exact command output. Remote MCP fits OAuth-scoped platform operations that do not need local files or CLI state.
25
26	Optional: if the current agent already has a user-installed local CLI MCP (`railway mcp`) configured, it can be used for CLI-backed platform operations not yet exposed by remote MCP. Published plugin configs do not install or launch local CLI MCP.
27
28	Use `scripts/railway-api.sh` for GraphQL only when neither MCP nor CLI exposes the operation, or when a reference gives a specific GraphQL fallback.
29
30	## Parsing Railway URLs
31
32	Users often paste Railway dashboard URLs. Extract IDs before doing anything else:
33
34	```
35	https://railway.com/project/<PROJECT_ID>/service/<SERVICE_ID>?environmentId=<ENV_ID>
36	https://railway.com/project/<PROJECT_ID>/service/<SERVICE_ID>
37	```
38
39	The URL always contains `projectId` and `serviceId`. It may contain `environmentId` as a query parameter. If the environment ID is missing and the user specifies an environment by name (e.g., "production"), resolve it:
40
41	```bash
42	scripts/railway-api.sh \
43	'query getProject($id: String!) {
44	project(id: $id) {
45	environments { edges { node { id name } } }
46	}
47	}' \
48	'{"id": "<PROJECT_ID>"}'
49	```
50
51	Match the environment name (case-insensitive) to get the `environmentId`.
52
53	Prefer passing explicit IDs to CLI commands (`--project`, `--environment`, `--service`) and scripts (`--project-id`, `--environment-id`, `--service-id`) instead of running `railway link`. This avoids modifying global state and is faster.
54
55	## Intent-based routing
56
57	Route by user intent before running preflight checks. The preflight ceremony below is for diagnostic and configuration work — it adds friction when the user just wants to ship something or sign up.

People who liked this also viewed

6 picks

Type