Use Railway
Railway resource model
Railway organizes infrastructure in a hierarchy:
- Workspace is the billing and team scope. A user belongs to one or more workspaces.
- Project is a collection of services under one workspace. It maps to one deployable unit of work.
- Environment is an isolated configuration plane inside a project (for example, , ). Each environment has its own variables, config, and deployment history.
- Service is a single deployable unit inside a project. It can be an app from a repo, a Docker image, or a managed database.
- Deployment is a point-in-time release of a service in an environment. It has build logs, runtime logs, and a status lifecycle.
Most CLI commands operate on the linked project/environment/service context. Use
to see the context, and
,
,
flags to override.
Preflight
Before any mutation, verify context:
bash
command -v railway # CLI installed
railway whoami --json # authenticated
railway --version # check CLI version
railway status --json # linked project/environment/service
If the CLI is missing, guide the user to install it.
bash
bash <(curl -fsSL cli.new) # Shell script (macOS, Linux, Windows via WSL)
brew install railway # Homebrew (macOS)
npm i -g @railway/cli # npm (macOS, Linux, Windows). Requires Node.js version 16 or higher.
If not authenticated, run
. If not linked, run
railway link --project <id-or-name>
.
If a command is not recognized (for example,
), the CLI may be outdated. Upgrade with:
Common quick operations
These are frequent enough to handle without loading a reference:
bash
railway status --json # current context
railway whoami --json # auth and workspace info
railway project list --json # list projects
railway service status --all --json # all services in current context
railway variable list --service <svc> --json # list variables
railway variable set KEY=value --service <svc> # set a variable
railway logs --service <svc> --lines 200 --json # recent logs
railway up --detach -m "<summary>" # deploy current directory
Routing
For anything beyond quick operations, load the reference that matches the user's intent. Load only what you need, one reference is usually enough, two at most.
| Intent | Reference | Use for |
|---|
| Create or connect resources | setup.md | Projects, services, databases, templates, workspaces |
| Ship code or manage releases | deploy.md | Deploy, redeploy, restart, build config, monorepo, Dockerfile |
| Change configuration | configure.md | Environments, variables, config patches, domains, networking |
| Check health or debug failures | operate.md | Status, logs, metrics, build/runtime triage, recovery |
| Request from API, docs, or community | request.md | Railway GraphQL API queries/mutations, metrics queries, Central Station, official docs |
If the request spans two areas (for example, "deploy and then check if it's healthy"), load both references and compose one response.
Execution rules
- Prefer Railway CLI. Fall back to for operations the CLI doesn't expose.
- Use output where available for reliable parsing.
- Resolve context before mutation. Know which project, environment, and service you're acting on.
- For destructive actions (delete service, remove deployment, drop database), confirm intent and state impact before executing.
- After mutations, verify the result with a read-back command.
Composition patterns
Multi-step workflows follow natural chains:
- First deploy: setup (create project + service), configure (set variables and source), deploy, operate (verify healthy)
- Fix a failure: operate (triage logs), configure (fix config/variables), deploy (redeploy), operate (verify recovery)
- Add a domain: configure (add domain + set port), operate (verify DNS and service health)
- Docs to action: request (fetch docs answer), route to the relevant operational reference
When composing, return one unified response covering all steps. Don't ask the user to invoke each step separately.
Setup decision flow
When the user wants to create or deploy something, determine the right action from current context:
- Run in the current directory.
- If linked: add a service to the existing project (
railway add --service <name>
- If not linked: check the parent directory (
cd .. && railway status --json
- Parent linked: this is likely a monorepo sub-app. Add a service and set to the sub-app path.
- Parent not linked: run and look for a project matching the directory name.
- Match found: link to it (
railway link --project <name>
- No match: create a new project (
railway init --name <name>
- When multiple workspaces exist, match by name from .
Naming heuristic: app names like "flappy-bird" or "my-api" are service names, not project names. Use the directory or repo name for the project.
Response format
For all operational responses, return:
- What was done (action and scope).
- The result (IDs, status, key output).
- What to do next (or confirmation that the task is complete).
Keep output concise. Include command evidence only when it helps the user understand what happened.