deploy current directory

railway bucket list --json

list buckets in current environment

railway bucket info --bucket < name

--json

bucket storage and object count

railway bucket credentials --bucket < name

--json

S3-compatible credentials

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, buckets, 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

scripts/railway-api.sh

for operations the CLI doesn't expose.

Use

--json

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:

Add object storage

setup (create bucket), setup (get credentials), configure (set S3 variables on app service)

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

railway status --json

in the current directory.

If linked

add a service to the existing project (

railway add --service

). Do not create a new project unless the user explicitly says "new project" or "separate project".

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

rootDirectory

to the sub-app path.

Parent not linked

run

railway list --json

and look for a project matching the directory name.

Match found

link to it (

railway link --project

).

No match

create a new project (

railway init --name

).

When multiple workspaces exist, match by name from

railway whoami --json

.

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.