Railway CLI for coding agents

When a coding agent has shell access to a project hosted on Railway, it can use Railway’s command-line interface (CLI) to inspect and manage Railway resources. A Railway project groups related services and environments. Each service is a deployed component, such as a web server or worker. For a read-only task, the agent can request service metrics in JSON and summarize them without changing a deployment.

The CLI sends requests to Railway through your authenticated account or token. Some commands also change your local machine. For example, railway setup agent configures the agent tools it detects. Keep local setup separate from commands that change Railway resources.

Install and connect

Railway’s CLI documentation provides an install command that installs the CLI and runs railway setup agent:

curl -fsSL agents.railway.com | sh

According to the setup reference, railway setup agent installs Railway’s use-railway skill and adds the Railway MCP server to the coding tools it supports. Claude Code and Cursor are on that list, and the page names the other tools. Running it again updates the Railway entries and leaves your other MCP servers in place. Check the agent’s configuration after setup to see what it added. If you want the CLI without this agent setup, the same documentation lists a plain installer and packages for Homebrew and npm.

Authenticate the CLI and link the working directory to a Railway project before querying its data:

railway login
railway link

railway login signs the CLI in, and railway link connects the current directory to a Railway project. Both commands contact Railway. Railway stores the link in a .railway directory in the project root. On a machine without a browser, such as an SSH session, railway login --browserless shows a pairing code and a URL that you open on another device. Sign in interactively yourself before asking an agent to use the project. Do not paste token values into the agent’s prompt.

Read metrics as JSON

Ask the agent to inspect a project’s service metrics and summarize what Railway reports. Run this command from the linked directory:

railway metrics --json

Without other flags, the metrics command reports on the linked service in the linked environment for the last hour. --service and --environment pick a different target, and --since and --until set the time window. Flags such as --cpu or --http limit the output to one group of metrics. It queries Railway and returns metric data; it does not deploy code or change project settings. The measurements depend on the project and the metrics selected.

A prompt can keep the agent’s task bounded:

Run railway metrics --json for the linked Railway project. Summarize the returned measurements and flag anything that looks unusual. Do not deploy, edit variables, or change project settings.

The agent can use the JSON response to write its summary. If the agent proposes a follow-up change, review the response yourself before making it. This command does not check whether a proposed fix works.

Keep authentication out of prompts

For automated runs, Railway documents RAILWAY_TOKEN for a project token and RAILWAY_API_TOKEN for an account or workspace token. Only one of the two may be set at a time, and setting both causes an error. A project token is scoped to one environment in one project. Railway lists deploying and managing variables among the things a project token can do, so treat it as a credential that can change the project. Store credentials in a protected environment or CI secret store, and keep them out of source code and prompts. Any token available to an agent process is also available to commands that process can run.

The command railway run is easy to misread. It makes service environment variables available to a command on your local machine. It does not open a shell on the Railway server or run the command there, as Railway’s run reference explains. Use it when local code needs Railway environment values. railway shell does the same for an interactive shell on your machine. Both put the service’s variables into a local process, so an agent that runs them can read those values. For a shell inside a deployed service, Railway has a separate command, railway ssh.