railway agent
Ask the Railway Agent about your project from the CLI. It answers questions, inspects deployments and logs, and makes changes using natural language. Run it without arguments for an interactive session, or send a single prompt with -p.
Usage
railway agent [OPTIONS]Options
| Flag | Description |
|---|---|
-p, --prompt <MESSAGE> | Send a single prompt (omit for interactive mode) |
--json | Output the response as JSON |
--list | List agent threads in the environment |
--thread-id <ID> | Continue an existing thread |
-s, --service <SERVICE> | Service to scope the conversation to (name or ID) |
-e, --environment <ENV> | Environment to use (defaults to the linked environment) |
--project <PROJECT> | Project ID (defaults to the linked project) |
-y, --accept | Skip the notice and wait before the cloud agent is first created. Alias: --yes. |
How it works
Each message you send is a task that runs on a cloud agent. The command shows the agent's progress, then prints the answer when the task finishes. Responses aren't streamed.
Every thread in an environment runs on one cloud agent named railway-agent. The first thread creates it, and later threads reuse it. The agent sleeps after five minutes idle and wakes on your next message.
A thread is a session on that agent. Its thread ID stays the same for the life of the thread.
Billing notice
Creating railway-agent starts a virtual machine, which is billed while it's active. The first time you run railway agent in an environment, the CLI prints a notice and waits five seconds before it creates the agent.
| Context | Behavior |
|---|---|
| With a terminal | Counts down from five. Press Enter to start at once, or Ctrl-C or Esc to cancel. |
| Without a terminal | Prints the notice, waits five seconds, then continues |
With --accept | Starts at once, with no notice |
Cancelling creates nothing. After the agent exists, there is no notice and no wait.
Examples
Start an interactive session
railway agentShow logs for your project
railway agent -p "show me the logs for my project"Debug a failing service
railway agent -p "help me debug why my backend service is failing"Check deployment status
railway agent -p "what's the status of my latest deployment?"Scope to a specific service
railway agent -p "check the logs for errors" --service backendWithout --service, the agent uses the linked service if there is one. The agent can see the whole environment either way. The service tells it what the conversation is about.
Use a project that isn't linked
railway agent -p "list my services" \
--project <project-id> --environment productionRun from a script
railway agent -p "list my services and their status" --json --acceptList previous threads
railway agent --listReturns the threads in the environment, with each thread's ID, number of turns, last activity, and opening prompt. Add --json for a machine-readable list.
Continue a previous thread
railway agent --thread-id <THREAD_ID>When you resume a thread, the CLI shows its most recent turns before the prompt. Add -p to send one message to the thread without entering interactive mode.
Interactive mode
When run without -p, the agent starts an interactive session:
$ railway agent
Railway Agent (type 'exit' or Ctrl+C to quit)
? You: what services do I have?
Railway Agent:
You have 3 services...
? You: show me the logs for the backend
Railway Agent:
Here are the recent logs...
? You: exit
Continue later with `railway agent --thread-id task-24250171c35d`.The agent keeps context within the thread, so follow-up questions build on earlier messages.
In interactive mode the agent can ask you things:
- When the agent asks a question, your next message is the answer.
- When the agent needs an approval, the CLI asks you to allow or deny it.
Press Ctrl-C while the agent is working to stop waiting and return to the prompt. The agent keeps working on that message.
JSON output
Use --json to get a structured response for scripting and automation:
railway agent -p "list my services" --jsonReturns a JSON object with:
{
"threadId": "task-24250171c35d",
"taskId": "6a667040-033b-4319-a24d-3d9fa1cdb1dd",
"status": "COMPLETED",
"response": "You have 3 services...",
"toolCalls": [{ "toolName": "list-services" }]
}| Field | Description |
|---|---|
threadId | Pass to --thread-id to continue the thread |
taskId | The task that ran this message |
status | COMPLETED, FAILED, CANCELLED, or AWAITING_INPUT |
response | The agent's answer |
toolCalls | The tools the agent used |
error | Present when status is FAILED |
questions | Present when status is AWAITING_INPUT |
With -p, the command exits non-zero when the message fails, is cancelled, or ends waiting on an answer. Without --json, piped output contains only the answer.
Authentication
The agent command requires user authentication via railway login. Project access tokens (RAILWAY_TOKEN) are not supported.