|Docs

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

FlagDescription
-p, --prompt <MESSAGE>Send a single prompt (omit for interactive mode)
--jsonOutput the response as JSON
--listList 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, --acceptSkip 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.

ContextBehavior
With a terminalCounts down from five. Press Enter to start at once, or Ctrl-C or Esc to cancel.
Without a terminalPrints the notice, waits five seconds, then continues
With --acceptStarts 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 agent

Show 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 backend

Without --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 production

Run from a script

railway agent -p "list my services and their status" --json --accept

List previous threads

railway agent --list

Returns 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" --json

Returns a JSON object with:

{
  "threadId": "task-24250171c35d",
  "taskId": "6a667040-033b-4319-a24d-3d9fa1cdb1dd",
  "status": "COMPLETED",
  "response": "You have 3 services...",
  "toolCalls": [{ "toolName": "list-services" }]
}
FieldDescription
threadIdPass to --thread-id to continue the thread
taskIdThe task that ran this message
statusCOMPLETED, FAILED, CANCELLED, or AWAITING_INPUT
responseThe agent's answer
toolCallsThe tools the agent used
errorPresent when status is FAILED
questionsPresent 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.