Railway CLI

https://github.com/railwayapp/cli
Admin
The Railway command line interface connects your code to your Railway project, allowing you to...
Tokens:92,609
Snippets:689
Trust Score:9.7
License:MIT
Update:4 days ago
Show doc for...
Tokens:
Raw
### Usage example: listing projects with favorites

Source: https://github.com/railwayapp/cli/blob/master/_autodocs/api-reference/workspace.md

Example showing how to fetch workspaces, pick one, get favorites, and print ranked projects with favorite markers.

```rust
use crate::workspace::{pick_workspace, workspaces, project_favorites_by_workspace};

let configs = Configs::new()?;
let client = GQLClient::new_authorized(&configs)?;
let all = workspaces_with_client(&client, &configs).await?;
let ws = pick_workspace(all.clone(), requested_workspace)?;
let favorites = project_favorites_by_workspace(&client, &configs,
    all.iter().map(|w| w.id().to_string()).collect()).await;
for (project, is_fav) in ws.projects_ranked(favorites.get(ws.id()).map(Vec::as_slice).unwrap_or(&[])) {
    println!("{} {}", if is_fav { "★" } else { "·" }, project.name());
}
```

--------------------------------

### Usage example (command → controller)

Source: https://github.com/railwayapp/cli/blob/master/_autodocs/api-reference/controllers.md

Example showing how to use the controllers to resolve a service context and fetch service variables.

```APIDOC
## Usage Example

### Description
Example of using `resolve_service_context` and `get_service_variables` to fetch variables for a service.

### Code
```rust
use crate::controllers::{project::resolve_service_context, variables::get_service_variables};

let ctx = resolve_service_context(args.project.clone(), args.service.clone(), args.environment.clone()).await?;
let vars = get_service_variables(&ctx.client, &ctx.configs, ctx.project_id.clone(), ctx.environment_id.clone(), ctx.service_id.clone()).await?;
let secrets = vars.get("DATABASE_URL");
```
```

--------------------------------

### Setup Local GraphQL-Backed MCP Server

Source: https://github.com/railwayapp/cli/blob/master/README.md

Opt into the local GraphQL-backed MCP server instead of the remote one. The comment shows an alternative focused command.

```bash
railway setup agent -y --local
# or
railway mcp install --local --agent cursor
```

--------------------------------

### Start an OpenCode server and open local client

Source: https://github.com/railwayapp/cli/blob/master/README.md

Prepares an authenticated server on a cloud agent and opens your local client. Use --name to override the generated agent name. OpenCode V2 is required; older images cannot run OpenCode sessions.

```bash
railway code --opencode
railway code --opencode --name my-box
```

--------------------------------

### Setup command arguments (src/commands/setup.rs)

Source: https://github.com/railwayapp/cli/blob/master/_autodocs/api-reference/commands-agents.md

Defines the CLI arguments for the `setup` command, including subcommands and flags for agent setup. The `--yes` flag skips prompts and is auto-engaged when stdout is not a TTY. The `--remote`, `--local`, and `--oauth` flags are mutually exclusive with specific conflicts.

```rust
pub struct Args { #[clap(subcommand)] command: SetupCommand }
enum SetupCommand { Agent(AgentArgs) }

pub struct AgentArgs {
    #[clap(short = 'y', long)] yes: bool,    // skip prompts; also auto-engaged when stdout is not a TTY
    #[clap(long, conflicts_with = "local")] remote: bool,   // CLI proxy default
    #[clap(long, conflicts_with_all = ["remote", "oauth"])] local: bool,
    #[clap(long, conflicts_with = "local")] oauth: bool,    // editor OAuth, takes precedence over --remote
}
```

--------------------------------

### Desktop setup commands for Claude, Codex, and OpenCode

Source: https://github.com/railwayapp/cli/blob/master/docs/cloud-agents.md

Commands to configure desktop integration for Claude, Codex, and OpenCode agents. Use --agent to select an existing VM and --dir to set the project directory. Setup writes configuration without opening the desktop app; restart the app to load the connection.

```sh
railway ca desktop --claude
railway ca desktop --codex
railway ca desktop --opencode --agent my-box
railway code --codex desktop-only --agent my-box --dir /app
```

--------------------------------

### Install graphql-client and generate schema

Source: https://github.com/railwayapp/cli/blob/master/CONTRIBUTING.md

Install the graphql-client CLI with cargo, then run the introspect-schema command to generate the GraphQL schema file at src/gql/schema.json.

```sh
cargo install graphql_client_cli
```

```sh
graphql-client introspect-schema https://backboard.railway.com/graphql/v2 > src/gql/schema.json
```

--------------------------------

### Usage example for Configs

Source: https://github.com/railwayapp/cli/blob/master/_autodocs/api-reference/config.md

Shows how to create a Configs instance, retrieve the linked project, check for auth credentials, link a project, and write the config. Requires the Configs type from crate::config.

```rust
use crate::config::Configs;

let mut configs = Configs::new()?;
let project = configs.get_linked_project().await?;       // resolves token/env/local
if !configs.has_auth_credentials() {
    // no RAILWAY_TOKEN, RAILWAY_API_TOKEN, or stored OAuth session
}
configs.link_project("p_abc".into(), Some("my-app".into()),
    "e_123".into(), Some("production".into()))?;
configs.write()?;
```

--------------------------------

### Install Railway CLI with agent support

Source: https://github.com/railwayapp/cli/blob/master/README.md

Installs the Railway CLI and configures detected agent tools in one step. Works on macOS, Linux, and Windows via WSL. Installs to ~/.railway/bin and runs railway setup agent.

```bash
bash <(curl -fsSL railway.com/install.sh) --agents -y
```

--------------------------------

### Setup Railway Agent Support

Source: https://github.com/railwayapp/cli/blob/master/README.md

Installs Railway skills and configures the remote Railway MCP server for detected AI coding tools.

```bash
railway setup agent -y
```

--------------------------------

### Usage example: reporter and retry utilities

Source: https://github.com/railwayapp/cli/blob/master/_autodocs/api-reference/util.md

Shows how to enable JSON output via `reporter::set_mode(true)` and use `retry_with_backoff` with a `RetryConfig` to retry an async operation with exponential backoff. The example uses `fetch_something().await` as a placeholder for the actual async call.

```rust
use crate::util::{reporter, retry::{RetryConfig, retry_with_backoff}};

reporter::set_mode(true);                       // JSON output
let data = retry_with_backoff(RetryConfig {
    max_attempts: 3, initial_delay_ms: 200, max_delay_ms: 2000,
    backoff_multiplier: 2.0, on_retry: None,
}, || async { fetch_something().await }).await?;
```

--------------------------------

### Query AgentBootstraps with post_graphql

Source: https://github.com/railwayapp/cli/blob/master/_autodocs/api-reference/gql-realtime.md

Usage example for querying bootstraps. Creates a `Configs` instance, an authorized `GQLClient`, and posts a GraphQL query for `AgentBootstraps` with the environment ID. Requires `Configs` and `GQLClient` to be in scope.

```rust
use crate::gql::bootstraps::{self, AgentBootstraps};
use crate::client::{GQLClient, post_graphql};

let configs = Configs::new()?;
let client = GQLClient::new_authorized(&configs)?;
let data = post_graphql::<AgentBootstraps, _>(&client, configs.get_backboard(), bootstraps::agent_bootstraps::Variables { environment_id: env_id }).await?;
```

--------------------------------

### Usage Pattern

Source: https://github.com/railwayapp/cli/blob/master/_autodocs/api-reference/gql-queries.md

Example of how to use a generated GraphQL query with the GQLClient and post_graphql helper.

```APIDOC
## Usage Pattern

### Description
Example of using a generated GraphQL query (e.g., Deployments) with the GQLClient and post_graphql helper.

### Code Example
```rust
use crate::gql::queries;
use crate::client::{GQLClient, post_graphql};

let configs = Configs::new()?;
let client = GQLClient::new_authorized(&configs)?;
let data = post_graphql::<queries::Deployments, _>(
    &client, configs.get_backboard(),
    queries::deployments::Variables { service_id: sid, limit: Some(10) },
).await?;
for edge in data.service.deployments.edges {
    println!("{} {}", edge.node.id, edge.node.status);
}
```
```

--------------------------------

### Usage example: resolve_service_context and get_service_variables

Source: https://github.com/railwayapp/cli/blob/master/_autodocs/api-reference/controllers.md

Shows how to resolve the service context and fetch service variables, then retrieve a specific secret like DATABASE_URL.

```rust
use crate::controllers::{project::resolve_service_context, variables::get_service_variables};

let ctx = resolve_service_context(args.project.clone(), args.service.clone(), args.environment.clone()).await?;
let vars = get_service_variables(&ctx.client, &ctx.configs, ctx.project_id.clone(), ctx.environment_id.clone(), ctx.service_id.clone()).await?;
let secrets = vars.get("DATABASE_URL");
```

--------------------------------

### Install MCP for Cursor Agent

Source: https://github.com/railwayapp/cli/blob/master/README.md

Focused command to install the MCP server for the Cursor agent.

```bash
railway mcp install --agent cursor
```

--------------------------------

### Utility types for install, retry, API, variables, logs, table, and theme

Source: https://github.com/railwayapp/cli/blob/master/_autodocs/types.md

Defines core utility types used across the CLI: install methods, retry configuration, API response structs, environment variable parsing, edit snapshots, log-fetch parameters, a table renderer, and theme definitions. The Variable type parses "KEY=VALUE" strings, treating a missing value as empty and rejecting malformed input. Theme is exposed through the tui_theme module with helpers for default, slug lookup, preference persistence, and iteration.

```rust
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum InstallMethod { Homebrew, Npm, Bun, Cargo, Shell, Scoop, Unknown }

pub struct RetryConfig {
    pub max_attempts: u32,
    pub initial_delay_ms: u64,
    pub max_delay_ms: u64,
    pub backoff_multiplier: f64,
    pub on_retry: Option<RetryCallback>,
}

#[derive(Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct UpResponse { pub deployment_id: String, pub url: String, pub logs_url: String, pub deployment_domain: String }
#[derive(Serialize, Deserialize)]
pub struct UpErrorResponse { pub message: String }

pub struct Variable { pub key: String, pub value: String }   // FromStr: "KEY=VALUE", KEY= ⇒ empty value, bad format bails

pub struct EditSnapshot { pub editable: BTreeMap<String, EditVariableEntry>, pub read_only: BTreeMap<String, String> }
pub struct EditVariableEntry { pub value: String, pub is_sealed: bool }

pub struct FetchLogsParams<'a> { pub client: &'a Client, pub backboard: &'a str, pub deployment_id: String, pub limit: Option<i64>, pub filter: Option<String>, pub start_date: Option<DateTime<Utc>>, pub end_date: Option<DateTime<Utc>> }
pub struct FetchNetworkFlowLogsParams<'a> / FetchDnsQueryLogsParams<'a>  // same, but environment_id + service_id

pub struct Table { ... }  // Table::new(name: String, rows: BTreeMap<String, String>) -> Self; get_string() -> Result<String>; print() -> Result<()>

pub struct Theme { pub slug: &'static str, pub label: &'static str, pub accent: Color, pub accent_dim: Color, pub dim: Color, pub fg: Color, pub on_accent: Color, pub surface: Color, pub sidebar: Color, pub selection: Color, pub running: Color, pub sleeping: Color, pub pending: Color, pub danger: Color, pub series: &'static [Color] }
pub const THEMES: &[Theme]
```

--------------------------------

### Install railway/iac SDK

Source: https://github.com/railwayapp/cli/blob/master/assets/iac/README.md

Install the railway package from the repository root to use the railway/iac imports in the TypeScript configuration file.

```bash
npm install railway
```

--------------------------------

### Prepare cloud agent for desktop apps

Source: https://github.com/railwayapp/cli/blob/master/README.md

Use these commands to prepare a cloud agent for Claude Code Desktop, Codex, or OpenCode Desktop. The --claude, --codex, and --opencode flags select the target desktop app; --agent and --new customize the agent. --codex is a compatibility alias for railway code --codex desktop-only.

```bash
railway ca desktop --claude
railway ca desktop --codex
railway ca desktop --opencode --agent my-box
railway ca desktop --opencode --new
```

--------------------------------

### GraphQL mutation to create VM from checkpoint with codeEndpoint

Source: https://github.com/railwayapp/cli/blob/master/README.md

Equivalent API request for creating a VM from a checkpoint with a custom code port. Uses the `cloudAgentCreate` mutation with `cloudAgentCheckpointId` and `codeEndpoint: { port: 5000 }`. The response includes the new VM's id, name, and domains.

```graphql
mutation {
  cloudAgentCreate(input: {
    environmentId: "<same-environment-id>"
    name: "restored-box"
    cloudAgentCheckpointId: "<checkpoint-id>"
    codeEndpoint: { port: 5000 }
  }) {
    id
    name
    domains { prefix port domain }
  }
}
```

--------------------------------

### Create VM with code endpoint (Codex/OpenCode and plain agent)

Source: https://github.com/railwayapp/cli/blob/master/README.md

Shows CLI commands to create a VM with the optional code endpoint. `railway code --codex --new` and `railway code --opencode --new` request it automatically for managed Codex/OpenCode clients. `railway ca create my-box --code-endpoint` explicitly requests it on a plain cloud agent. Use `--code-port 5000` to choose a custom port instead of the default 4096.

```bash
railway code --codex --new
railway code --opencode --new

# Explicitly request the endpoint on a plain cloud agent:
railway ca create my-box --code-endpoint

# Choose a custom port instead of the default 4096:
railway code --opencode --new --code-port 5000
railway ca create my-box --code-port 5000
```

--------------------------------

### Railway CLI: Save and use bootstraps, create VM from checkpoint

Source: https://github.com/railwayapp/cli/blob/master/docs/cloud-agents.md

Saves a VM bootstrap for reuse)Skiphedges with a name, agent, and optional default. Uses the bootstrap when starting a Codex clientholis and creates a VM from a checkpoint. Supports variables via --variable and --env-file; explicit variables override matching file entries.

```sh
railway ca bootstrap save dev --agent my-box --default
railway code --codex --bootstrap dev
railway ca create my-box --from-checkpoint <checkpoint-id>
```

--------------------------------

### Reconnect to an existing OpenCode server

Source: https://github.com/railwayapp/cli/blob/master/README.md

Discovers running OpenCode servers on agents you own. Use a name or ID to target an agent directly. Multiple matches show a picker; in noninteractive terminals, a name or ID is required.

```bash
railway code --opencode connect
railway code --opencode connect my-box
```

--------------------------------

### Install Railway CLI without agent configuration

Source: https://github.com/railwayapp/cli/blob/master/README.md

Installs the Railway CLI without configuring agent tools. Suitable when agent setup is not needed.

```bash
bash <(curl -fsSL railway.com/install.sh) -y
```

--------------------------------

### Restore VM from checkpoint with code endpoint

Source: https://github.com/railwayapp/cli/blob/master/README.md

Shows CLI commands to create a new VM from a checkpoint and attach a code endpoint. `railway ca create restored-box --from-checkpoint <checkpoint-id> --code-endpoint` uses the default port, while `--code-port 5000` selects a custom port. Then `railway code --opencode --agent restored-box` launches OpenCode against the restored VM.

```bash
railway ca create restored-box --from-checkpoint <checkpoint-id> --code-endpoint
# Or select a custom port:
railway ca create restored-box --from-checkpoint <checkpoint-id> --code-port 5000
railway code --opencode --agent restored-box
```

--------------------------------

### railway code --codex terminal setup commands

Source: https://github.com/railwayapp/cli/blob/master/README.md

Run the native Codex terminal UI connected to a persistent Railway cloud agent. New agents use a `codex-` prefix and the generated name works with `connect`, `get-config`, and cloud-agent lifecycle commands; `--name` sets a custom name.

```bash
railway code --codex
railway code --codex --agent my-box --dir /app
railway code --codex connect my-box
railway code --codex connect
```

--------------------------------

### Remote client and argument passing

Source: https://github.com/railwayapp/cli/blob/master/docs/cloud-agents.md

Shows how to run the client on the VM with the remote flag and how to pass arguments to the agent using --.

```sh
railway code --codex remote
railway code --codex -- exec "explain this codebase"
```

--------------------------------

### railway code --codex desktop-only workflow

Source: https://github.com/railwayapp/cli/blob/master/README.md

Prepare the VM for a Desktop-only workflow without launching a local terminal client. Starts or reuses the authenticated backend App Server, verifies its public endpoint, registers SSH, and saves the remote project for Codex Desktop to import at next startup, then exits.

```bash
railway code --codex desktop-only
railway code --codex desktop-only --agent my-box --dir /app
```

--------------------------------

### Install Skills for Claude Code Agent

Source: https://github.com/railwayapp/cli/blob/master/README.md

Focused command to install Railway skills for the Claude Code agent.

```bash
railway skills --agent claude-code
```

--------------------------------

### Usage pattern for executing a GraphQL query

Source: https://github.com/railwayapp/cli/blob/master/_autodocs/api-reference/gql-queries.md

Shows how to use the generated query structs with the GQLClient and post_graphql helper. It creates a client, sends a Deployments query with variables, and prints the deployment edges.

```rust
use crate::gql::queries;
use crate::client::{GQLClient, post_graphql};

let configs = Configs::new()?;
let client = GQLClient::new_authorized(&configs)?;
let data = post_graphql::<queries::Deployments, _>(
    &client, configs.get_backboard(),
    queries::deployments::Variables { service_id: sid, limit: Some(10) },
).await?;
for edge in data.service.deployments.edges {
    println!("{} {}", edge.node.id, edge.node.status);
}
```

--------------------------------

### SandboxCreate

Source: https://github.com/railwayapp/cli/blob/master/_autodocs/api-reference/gql-mutations.md

Creates a sandbox with project, environment, instructions, and base image digest.

```APIDOC
## SandboxCreate

### Description
Creates a sandbox.

### Variables
- **project_id** (String) - Required - The ID of the project.
- **environment_id** (String) - Required - The ID of the environment.
- **instructions** (String) - Required - Instructions for the sandbox.
- **base_image_digest** (String) - Required - Digest of the base image.
- ... (additional fields)

### Example (Rust)
```rust
queries::sandbox_create::Variables { project_id, environment_id, instructions, base_image_digest, ... }
```
```

--------------------------------

### railway code --railway command variants

Source: https://github.com/railwayapp/cli/blob/master/README.md

Commands for launching the local Railway TUI on a new or existing VM, connecting, running remotely, verifying setup, and replaying saved connection details. `connect` is only for reusing an existing VM; `--agent` targets a specific VM; `--dir` selects the remote project (default `/app`); `--connection-json` verifies without opening the TUI.

```bash
railway code --railway                       # new VM, local TUI on its public agent endpoint
railway code --railway --agent my-box --dir /app/project
railway code --railway connect my-box        # connect to an existing VM; wake it if asleep
railway code --railway remote                # run the TUI on a new VM over SSH
railway code --railway --connection-json     # setup and verify, without opening a TUI
railway code get-config my-box               # replay saved connection details
```

--------------------------------

### workspaces()

Source: https://github.com/railwayapp/cli/blob/master/_autodocs/api-reference/workspace.md

Shortcut that builds Configs and an authorized GQLClient, then calls workspaces_with_client to fetch all workspaces for the authenticated user.

```APIDOC
## [GET] /workspaces

### Description
Shortcut that builds Configs and an authorized GQLClient, then calls workspaces_with_client to fetch all workspaces for the authenticated user.

### Method
GET

### Endpoint
/workspaces

### Parameters
None

### Request Example
{}

### Response
#### Success Response (200)
- **workspaces** (Vec<Workspace>) - List of workspaces

#### Response Example
{
  "workspaces": []
}
```

--------------------------------

### Open SSH shells and resume Claude conversations with railway ca ssh

Source: https://github.com/railwayapp/cli/blob/master/README.md

Use `railway ca ssh` to open a login shell, attach to or start a durable session, attach to a named session, or resume the latest Claude conversation. Plain SSH bypasses harness autostart. In the CA frame, Option+O / Alt+O opens a shell on the selected VM and returns to the frame on exit; the sidebar's `c` action copies the shell command.

```bash
railway ca ssh my-box                 # open a login shell
railway ca ssh my-box --session       # attach to or start a durable session
railway ca ssh my-box --session name  # attach to a named session
railway ca ssh my-box --resume        # resume the latest Claude conversation
```

--------------------------------

### ServiceInstance

Source: https://github.com/railwayapp/cli/blob/master/_autodocs/api-reference/gql-queries.md

Query for service instance plus source and root deployment.

```APIDOC
## ServiceInstance

### Description
Service instance + source + root deployment

### Query
ServiceInstance

### Source File
ServiceInstance.graphql
```

--------------------------------

### get_tcp_proxy

Source: https://github.com/railwayapp/cli/blob/master/_autodocs/api-reference/mcp-server.md

Gets a TCP proxy by selector.

```APIDOC
## get_tcp_proxy

### Description
Gets a TCP proxy by selector.

### Parameters
- `TcpProxySelectorParams` - Input parameters for the tool.

### Response
Returns `Result<CallToolResult, McpError>`.
```

--------------------------------

### workspaces() function signature

Source: https://github.com/railwayapp/cli/blob/master/_autodocs/api-reference/workspace.md

Shortcut that builds Configs and GQLClient, then calls workspaces_with_client.

```rust
pub async fn workspaces() -> Result<Vec<Workspace>>
```

--------------------------------

### Basic typed query with GQLClient

Source: https://github.com/railwayapp/cli/blob/master/_autodocs/api-reference/client.md

Shows a basic typed GraphQL query using the GQLClient and post_graphql helper. It creates a new authorized client from configs, posts a DeploymentStatus query with a deployment ID variable, and prints the resulting status.

```rust
use crate::client::{GQLClient, post_graphql};
use crate::gql::queries;

let configs = Configs::new()?;
let client = GQLClient::new_authorized(&configs)?;
let data = post_graphql::<queries::DeploymentStatus, _>(
    &client,
    configs.get_backboard(),
    queries::deployment_status::Variables { id: deployment_id.to_owned() },
).await?;
println!("status: {:?}", data.deployment.status);
```

--------------------------------

### variables::reject_reserved_keys

Source: https://github.com/railwayapp/cli/blob/master/_autodocs/api-reference/controllers.md

Rejects keys that start with `RAILWAY_` (reserved).

```APIDOC
## reject_reserved_keys

### Description
Rejects keys that start with `RAILWAY_` (reserved).

### Method
Function

### Parameters
- keys - Required - The keys to validate.

### Returns
- `Result<()>` - Error if any reserved key is present.

```

--------------------------------

### SandboxCreate

Source: https://github.com/railwayapp/cli/blob/master/_autodocs/api-reference/gql-mutations.md

Creates a sandbox.

```APIDOC
## SandboxCreate

### Description
Create a sandbox.

### Mutation
`SandboxCreate`

### GraphQL File
`SandboxCreate.graphql`

```

--------------------------------

### Initialize Railway configuration

Source: https://github.com/railwayapp/cli/blob/master/assets/iac/README.md

Creates the configuration files for the Railway project.

```bash
railway config init
```

--------------------------------

### variables::is_railway_reserved_key

Source: https://github.com/railwayapp/cli/blob/master/_autodocs/api-reference/controllers.md

Checks whether a key is a Railway reserved key (starts with `RAILWAY_`).

```APIDOC
## is_railway_reserved_key

### Description
Checks whether a key is a Railway reserved key (starts with `RAILWAY_`).

### Method
Function

### Parameters
- `key` - Required - The key to check.

### Returns
- `bool` - `true` if the key is reserved, `false` otherwise.

```

--------------------------------

### deploy

Source: https://github.com/railwayapp/cli/blob/master/_autodocs/api-reference/mcp-server.md

Uploads and deploys a directory.

```APIDOC
## deploy

### Description
Uploads and deploys a directory.

### Parameters
- `DeployParams` - Input parameters including `path` and `message`.

### Response
Returns `Result<CallToolResult, McpError>`.
```

--------------------------------

### new_authorized constructor

Source: https://github.com/railwayapp/cli/blob/master/_autodocs/api-reference/client.md

Creates an authorized client. Auth header precedence: RAILWAY_TOKEN → project-access-token header; else configs.get_railway_auth_token() → authorization: Bearer <token>; else returns RailwayError::Unauthorized.

```rust
pub fn new_authorized(configs: &Configs) -> Result<Client, RailwayError>
```

--------------------------------

### Uninstall Railway CLI

Source: https://github.com/railwayapp/cli/blob/master/README.md

Removes the Railway CLI from the system.

```bash
bash <(curl -fsSL cli.new) -r
```

--------------------------------

### Authenticate with Railway CLI

Source: https://github.com/railwayapp/cli/blob/master/README.md

Interactive login for the Railway CLI. Use in a browser-enabled environment.

```bash
railway login
```

--------------------------------

### create_project

Source: https://github.com/railwayapp/cli/blob/master/_autodocs/api-reference/mcp-server.md

Creates a project, name is required.

```APIDOC
## create_project

### Description
Creates a project, name is required.

### Parameters
- `CreateProjectParams` - Input parameters including `name` (required).

### Response
Returns `Result<CallToolResult, McpError>`.
```

--------------------------------

### workspaces_with_client(client, configs)

Source: https://github.com/railwayapp/cli/blob/master/_autodocs/api-reference/workspace.md

Runs the UserProjects query to fetch workspaces. Member workspaces are yielded before external ones, duplicate ids are de-duplicated, and the list is sorted by id descending.

```APIDOC
## [GET] /workspaces/with-client

### Description
Runs the UserProjects query to fetch workspaces. Member workspaces are yielded before external ones, duplicate ids are de-duplicated, and the list is sorted by id descending.

### Method
GET

### Endpoint
/workspaces/with-client

### Parameters
#### Query Parameters
- **client** (reqwest::Client) - Required - HTTP client
- **configs** (Configs) - Required - Configuration object

### Request Example
{}

### Response
#### Success Response (200)
- **workspaces** (Vec<Workspace>) - List of workspaces

#### Response Example
{
  "workspaces": []
}
```

--------------------------------

### OpenCode version error message

Source: https://github.com/railwayapp/cli/blob/master/docs/cloud-agents.md

Error message shown when starting or resuming an OpenCode session on an agent created from an older image that has OpenCode 1.x.

```text
This cloud agent is on an older image whose OpenCode is not V2. Create a new agent with railway code --opencode --new.
```

--------------------------------

### VolumeInstanceBackupCreate

Source: https://github.com/railwayapp/cli/blob/master/_autodocs/api-reference/gql-mutations.md

Creates a volume backup.

```APIDOC
## VolumeInstanceBackupCreate

### Description
Create a volume backup.

### Mutation
`VolumeInstanceBackupCreate`

### GraphQL File
`VolumeInstanceBackupCreate.graphql`

```

--------------------------------

### Browserless Login for SSH Sessions

Source: https://github.com/railwayapp/cli/blob/master/README.md

Use --browserless for environments without a browser, such as SSH sessions.

```bash
railway login --browserless
```

--------------------------------

### create_environment

Source: https://github.com/railwayapp/cli/blob/master/_autodocs/api-reference/mcp-server.md

Creates an environment, optionally forked.

```APIDOC
## create_environment

### Description
Creates an environment, optionally forked.

### Parameters
- `CreateEnvironmentParams` - Input parameters for the tool.

### Response
Returns `Result<CallToolResult, McpError>`.
```

--------------------------------

### create_bucket

Source: https://github.com/railwayapp/cli/blob/master/_autodocs/api-reference/mcp-server.md

Creates a bucket.

```APIDOC
## create_bucket

### Description
Creates a bucket.

### Parameters
- `CreateBucketParams` - Input parameters for the tool.

### Response
Returns `Result<CallToolResult, McpError>`.
```

--------------------------------

### Set RAILWAY_TOKEN for Project-Level Actions

Source: https://github.com/railwayapp/cli/blob/master/README.md

For CI/CD pipelines, set RAILWAY_TOKEN to authenticate project-level actions. Replace xxx with your token.

```bash
RAILWAY_TOKEN=xxx railway up
```

--------------------------------

### environment_status

Source: https://github.com/railwayapp/cli/blob/master/_autodocs/api-reference/mcp-server.md

Returns environment, service, and deployment summary.

```APIDOC
## environment_status

### Description
Returns environment, service, and deployment summary.

### Parameters
- `EnvironmentStatusParams` - Input parameters for the tool.

### Response
Returns `Result<CallToolResult, McpError>`.
```

--------------------------------

### check_updates command Args struct

Source: https://github.com/railwayapp/cli/blob/master/_autodocs/api-reference/commands-agents.md

Placeholder struct for check_updates command arguments, with comments indicating --yes, --json, and --install flags. The actual fields are not shown.

```rust
pub struct Args { /* --yes/--json/--install? */ }
```

--------------------------------

### RailwayMcp key methods

Source: https://github.com/railwayapp/cli/blob/master/_autodocs/api-reference/mcp-server.md

Lists the key methods on RailwayMcp. sync_client refreshes and swaps the HTTP client, returning true if the token changed; it is called at the start of every tool call.

```rust
pub fn new(client: reqwest::Client, configs: Configs) -> Self
pub(crate) fn client(&self) -> reqwest::Client
pub(crate) async fn sync_client(&self, force: bool) -> bool   // refresh + swap; true if token changed
pub(crate) async fn resolve_context(&self, project_id: Option<String>, environment_id: Option<String>) -> Result<ResolvedContext, McpError>
pub(crate) async fn get_latest_deployment_id(&self, project_id: &str, environment_id: &str, service_id: Option<&str>) -> ...
pub(crate) async fn resolve_service_context(&self, params: &ServiceParams) -> Result<ResolvedServiceContext, McpError>
pub(crate) async fn fetch_domains(&self, project_id: &str, environment_id: &str, service_id: &str) -> ...
pub(crate) async fn resolve_domain_details(&self, project_id: &str, environment_id: &str, service_id: &str, domain: &str) -> ...
```

--------------------------------

### deployment::fetch_build_logs

Source: https://github.com/railwayapp/cli/blob/master/_autodocs/api-reference/controllers.md

Fetches build logs for a deployment.

```APIDOC
## fetch_build_logs

### Description
Fetches build logs for a deployment.

### Method
Function

### Parameters
- `params` - Required - `FetchLogsParams` with `client`, `backboard`, `deployment_id`, `limit`, `filter`, `start_date`, `end_date`.

### Returns
- `Result<Vec<serde_json::Value>>` - List of log entries.

```

--------------------------------

### SandboxTemplateBuild

Source: https://github.com/railwayapp/cli/blob/master/_autodocs/api-reference/gql-mutations.md

Builds a sandbox template.

```APIDOC
## SandboxTemplateBuild

### Description
Build a sandbox template.

### Mutation
`SandboxTemplateBuild`

### GraphQL File
`SandboxTemplateBuild.graphql`

```

--------------------------------

### Telemetry event and preferences types

Source: https://github.com/railwayapp/cli/blob/master/_autodocs/types.md

Defines telemetry event structures for tracking CLI commands, setup agent phases, MCP clients, and authentication events. Includes a Preferences struct for telemetry and auto-update settings.

```rust
pub struct CliTrackEvent {
    pub command: String,
    pub sub_command: Option<String>,
    pub duration_ms: u64,
    pub success: bool,
    pub error_message: Option<String>,
    pub os: &'static str,
    pub arch: &'static str,
    pub cli_version: &'static str,
    pub is_ci: bool,
}
pub struct SetupAgentTrackEvent { pub phase: SetupAgentPhase, pub success: Option<bool>, pub error_message: Option<String>, pub configured_clients: Option<Vec<String>> }
pub enum SetupAgentPhase { Start, Finish }
#[derive(Clone, Debug)]
pub struct McpClientInfo { pub name: String }
pub struct CliAuthTrackEvent {
    pub transport: &'static str,        // "browser" | "device_code"
    pub outcome: &'static str,          // "succeeded" | "timed_out" | "failed"
    pub transport_reason: &'static str, // "browser"|"flag_browserless"|"env_ci"|"env_ssh"|"no_display"|"open_failed_fallback"
    pub success: bool,
    pub error_message: Option<String>,
}
pub struct Preferences { pub telemetry_disabled: bool, pub auto_update_disabled: bool }
```

--------------------------------

### add command Args struct

Source: https://github.com/railwayapp/cli/blob/master/_autodocs/api-reference/commands-core.md

Defines the `add` command's arguments for adding a database or deployable service. Supports `--database`, `--service`, `--repo`, `--branch`, `--image`, `--variables`, `--verbose`, and `--json` flags.

```rust
pub struct Args {
    #[arg(short, long, value_enum)] database: Vec<DatabaseType>,  // postgres, mysql, redis, …
    #[clap(short, long)] service: Option<Option<String>>,         // service name (blank ⇒ random)
    #[clap(short, long)] repo: Option<String>,                    // GitHub owner/repo source
    #[clap(long, requires = "repo")] branch: Option<String>,
    #[clap(short, long)] image: Option<String>,                   // docker image source
    #[clap(short, long)] variables: Vec<Variable>,                // KEY=VALUE pairs
    #[clap(long, action = clap::ArgAction::Set, num_args = 0..=1, default_missing_value = "true")] verbose: Option<bool>,
    #[clap(long)] json: bool,
}
```

--------------------------------

### deployment::BuildLogContext

Source: https://github.com/railwayapp/cli/blob/master/_autodocs/api-reference/controllers.md

Provides a context for streaming build logs. It is created with `new` or loaded from an existing deployment, and can stream log variables.

```APIDOC
## BuildLogContext

### Description
Provides a context for streaming build logs. It is created with `new` or loaded from an existing deployment, and can stream log variables.

### Constructor
- `new(environment_id: String, snapshot_id: Option<String>, created_at: DateTime<Utc>) -> Option<Self>`
- `load(client: &Client, backboard: &str, deployment_id: &str) -> Result<Self>`

### Methods
- `stream_variables(filter: Option<&str>) -> environment_logs::Variables` - Streams variables with an optional filter.

```

--------------------------------

### Run OpenCode client and server inside cloud agent

Source: https://github.com/railwayapp/cli/blob/master/README.md

Runs both client and server inside the cloud agent in Railway CA. Use --agent to target an existing agent. Harness-specific arguments go after --.

```bash
railway code --opencode remote
```

--------------------------------

### VolumeInstancePitrRestore

Source: https://github.com/railwayapp/cli/blob/master/_autodocs/api-reference/gql-mutations.md

Restores from PITR.

```APIDOC
## VolumeInstancePitrRestore

### Description
Restore from PITR.

### Mutation
`VolumeInstancePitrRestore`

### GraphQL File
`VolumeInstancePitrRestore.graphql`

```

--------------------------------

### railway init: Args

Source: https://github.com/railwayapp/cli/blob/master/_autodocs/api-reference/commands-core.md

Defines the CLI arguments for `railway init` (alias `new`). Accepts an optional project name, workspace, and a JSON output flag.

```rust
pub struct Args {
    #[clap(short, long)] name: Option<String>,     // project name
    #[clap(short, long)] workspace: Option<String>,// workspace id or name
    #[clap(long)] json: bool,
}
```

--------------------------------

### Railway CLI: get-config and connect with --connection-json

Source: https://github.com/railwayapp/cli/blob/master/docs/cloud-agents.md

Shows local connection snapshots without login or network access. Use --json for structured output with credentials. Does not verify connectivity. Scoped to Codex or OpenCode, use --codex and --connection-json to get verified details.

```sh
railway code get-config
railway code get-config my-box --json
railway code --codex connect my-box --connection-json
```

--------------------------------

### metrics command arguments (Rust comment)

Source: https://github.com/railwayapp/cli/blob/master/_autodocs/api-reference/commands-deploy.md

Shows the CLI arguments for the `metrics` command. Includes service selection, time range (`--since` default "1h"), JSON/raw output, and a watch mode (`-w`) that opens a ratatui TUI. HTTP status and path filters are available.

```rust
// Args: -s/--service, -a/--all, -e/--environment, -p/--project,
// --since (default "1h"), --until, --json, --raw,
// -w/--watch (TUI), HTTP selects: --http-status, --http-path, ...
```

--------------------------------

### Catch RailwayError variants in consumer code

Source: https://github.com/railwayapp/cli/blob/master/_autodocs/errors.md

Match on a downcasted RailwayError to handle specific error variants: Ratelimited (server 429), OAuthInvalidGrant (credentials already cleared, guide to `railway login`), and EnvironmentRestricted (ask admin for access). Unmatched errors are returned to main() for rendering with exit code 1.

```rust
use crate::errors::RailwayError;

let result = some_railway_call().await;
if let Err(e) = result {
    match e.downcast_ref::<RailwayError>() {
        Some(RailwayError::Ratelimited { retry_after_secs }) => {
            eprintln!("backing off for {:?}", retry_after_secs); // server 429
        }
        Some(RailwayError::OAuthInvalidGrant(_)) => {
            // credentials already cleared; guide the user to `railway login`
        }
        Some(RailwayError::EnvironmentRestricted(name)) => {
            eprintln!("ask an admin for access to {name}");
        }
        _ => return Err(e), // let main() render it (exit 1)
    }
}
```

--------------------------------

### SandboxTemplateBuild

Source: https://github.com/railwayapp/cli/blob/master/_autodocs/api-reference/gql-queries.md

Query for sandbox template build status.

```APIDOC
## SandboxTemplateBuild

### Description
Sandbox template build status

### Query
SandboxTemplateBuild

### Source File
SandboxTemplateBuild.graphql
```

--------------------------------

### create_volume

Source: https://github.com/railwayapp/cli/blob/master/_autodocs/api-reference/mcp-server.md

Creates a volume.

```APIDOC
## create_volume

### Description
Creates a volume.

### Parameters
- `CreateVolumeParams` - Input parameters for the tool.

### Response
Returns `Result<CallToolResult, McpError>`.
```

--------------------------------

### railway code --codex connection-json, remote, and exec commands

Source: https://github.com/railwayapp/cli/blob/master/README.md

For scripts, `--connection-json` returns a single JSON object with `schemaVersion`, agent identity, and connection `url`, `token`, `directory`, `version`, and `reused`; progress goes to stderr. `remote` runs the UI inside Railway CA, and `-- exec` executes inside the VM.

```bash
railway code --codex --connection-json connect my-box
railway code --codex remote             # run the UI inside Railway CA
railway code --codex -- exec "run tests" # execute inside the VM
```

--------------------------------

### railway ca bootstrap save/list/default and railway code bootstrap usage

Source: https://github.com/railwayapp/cli/blob/master/README.md

Commands to save, list, set default, and use cloud agent bootstraps. Includes railway code with --codex, --bootstrap, --no-bootstrap, and railway ca create with --bootstrap. The launcher and keyboard shortcuts (Option+B, n, Option+N) manage bootstraps; failed captures are hidden from pickers.

```bash
railway ca bootstrap save dev --agent configured-vm
railway ca bootstrap list
railway ca bootstrap save updated --agent another-vm --default
railway ca bootstrap default dev

railway code --codex                         # uses your local environment default
railway code --codex --bootstrap updated     # selects a named bootstrap
railway code --codex --no-bootstrap          # starts with a clean VM
railway ca create scratch --bootstrap dev
```

--------------------------------

### deployment::fetch_dns_query_logs

Source: https://github.com/railwayapp/cli/blob/master/_autodocs/api-reference/controllers.md

Fetches DNS query logs for an environment (optionally filtered by service).

```APIDOC
## fetch_dns_query_logs

### Description
Fetches DNS query logs for an environment (optionally filtered by service).

### Method
Function

### Parameters
- `params` - Required - `FetchDnsQueryLogsParams` with `client`, `backboard`, `environment_id`, `service_id`, `limit`, `filter`, `start_date`, `end_date`.

### Returns
- `Result<Vec<...>>` - List of DNS query log entries.

```

--------------------------------

### Preview Railway changes

Source: https://github.com/railwayapp/cli/blob/master/assets/iac/README.md

Shows a preview of what Railway would change.

```bash
railway config plan
```

--------------------------------

### Retrieve saved connection configuration with railway code get-config

Source: https://github.com/railwayapp/cli/blob/master/README.md

Use `railway code get-config` to retrieve the most recently saved connection, a specific agent by name, a generated name, or an agent ID. Works from any directory using local snapshots without login or network access. `--json` includes saved agent/SSH metadata and harness-specific objects with credentials and Desktop status; these are saved details, not a live health check.

```bash
railway code get-config                  # most recently saved connection
railway code get-config my-box           # a specific agent by name
railway code get-config codex-railg-3ed   # generated names work too
railway code get-config <agent-id>        # use an ID if names are ambiguous
railway code get-config my-box --json
```

--------------------------------

### deployment::fetch_http_logs

Source: https://github.com/railwayapp/cli/blob/master/_autodocs/api-reference/controllers.md

Fetches HTTP logs for a deployment.

```APIDOC
## fetch_http_logs

### Description
Fetches HTTP logs for a deployment.

### Method
Function

### Parameters
- `params` - Required - `FetchLogsParams`-like with relevant fields.

### Returns
- `Result<Vec<HttpLogLine>>` - List of HTTP log lines.

```

--------------------------------

### Expanded macro functions: build_args and exec_cli

Source: https://github.com/railwayapp/cli/blob/master/_autodocs/api-reference/cli.md

The `commands!` macro expands to these two public functions. `build_args()` constructs the root `clap::Command` named `"railway"` with `.about()`, `.version()`, and one subcommand per module. `exec_cli()` matches the parsed subcommand, calls the module's `command(args)` handler, and records a telemetry `CliTrackEvent` on every invocation.

```rust
pub fn build_args() -> clap::Command
```

```rust
pub async fn exec_cli(matches: clap::ArgMatches) -> anyhow::Result<()>
```

--------------------------------

### trace command subcommands enum

Source: https://github.com/railwayapp/cli/blob/master/_autodocs/api-reference/commands-data.md

Defines the subcommands for the `trace` command (aliases `traces`, `tracing`). `Enable` turns tracing on for a service or `--all`; `Disable` turns it off; `Status` shows settings and last export with `-a`/`--all`; `List` (alias `ls`) supports `--since`/`-S` (default `1h`), `--until`/`-U`, `-n`/`--limit`, `--service`, and `-a`/`--all`; `Get` (alias `show`) takes a 32-hex W3C `trace_id` and `--max-spans` (default 1000, max 2000). Uses `TracingStatus`, `Traces`, `Trace` queries and signal mutations for enable/disable.

```rust
// Args: subcommand + global -s, -e, -p, --environment, --json
enum Commands {
    Enable(SwitchArgs),      // tracing on for a service, or --all
    Disable(SwitchArgs),     // tracing off
    Status { #[clap(short = 'a', long)] all: bool },   // settings + last export
    List(ListArgs),          // alias "ls": --since/-S (default "1h"), --until/-U, -n/--limit, --service, -a/--all
    Get { trace_id: String /* 32-hex W3C, parse_trace_id */, --max-spans (default 1000, max 2000) },  // alias "show"
}
```

--------------------------------

### new_public constructor

Source: https://github.com/railwayapp/cli/blob/master/_autodocs/api-reference/client.md

Creates a client without auth headers, only x-source: CLI <version>. Used for anonymous template lookup/search.

```rust
pub fn new_public() -> Result<Client, RailwayError>
```

--------------------------------

### deployment::fetch_deploy_logs

Source: https://github.com/railwayapp/cli/blob/master/_autodocs/api-reference/controllers.md

Fetches deploy logs for a deployment.

```APIDOC
## fetch_deploy_logs

### Description
Fetches deploy logs for a deployment.

### Method
Function

### Parameters
- `params` - Required - `FetchLogsParams` with `client`, `backboard`, `deployment_id`, `limit`, `filter`, `start_date`, `end_date`.

### Returns
- `Result<Vec<serde_json::Value>>` - List of log entries.

```

--------------------------------

### deploy_template

Source: https://github.com/railwayapp/cli/blob/master/_autodocs/api-reference/mcp-server.md

Deploys a template by code.

```APIDOC
## deploy_template

### Description
Deploys a template by code.

### Parameters
- `DeployTemplateParams` - Input parameters for the tool.

### Response
Returns `Result<CallToolResult, McpError>`.
```

--------------------------------

### CloudAgentCreate

Source: https://github.com/railwayapp/cli/blob/master/_autodocs/api-reference/gql-mutations.md

Creates a cloud agent VM.

```APIDOC
## CloudAgentCreate

### Description
Create a cloud agent VM.

### Mutation
`CloudAgentCreate`

### GraphQL File
`CloudAgentCreate.graphql`

```

--------------------------------

### CI review workflow for partial release

Source: https://github.com/railwayapp/cli/blob/master/assets/iac/README.md

Generates a JSON preview for review, then applies the release using the baseConfigEtag from that preview. The --yes flag confirms without prompting, and --json proceeds without prompting. Requires environment ADMIN access.

```bash
railway config partials release operations --dry-run --json > ownership-preview.json
# After reviewing that preview, pass its baseConfigEtag with the same command:
railway config partials release operations \
  --base-config-etag "$(jq -r .baseConfigEtag ownership-preview.json)" --yes --json
```

--------------------------------

### workspaces_with_client() function signature

Source: https://github.com/railwayapp/cli/blob/master/_autodocs/api-reference/workspace.md

Runs the UserProjects query. Member workspaces are yielded before external ones, duplicates are de-duplicated, and the list is sorted by id descending.

```rust
pub async fn workspaces_with_client(
    client: &reqwest::Client,
    configs: &Configs,
) -> Result<Vec<Workspace>>
```

--------------------------------

### hint()

Source: https://github.com/railwayapp/cli/blob/master/_autodocs/api-reference/errors.md

Returns an actionable next step for the error, surfaced as the 'hint' field in structured output. Provides guidance for common errors such as authentication and project linking.

```APIDOC
## hint()

### Description
Returns an actionable next step for the error, surfaced as the `hint` field in structured output.

### Method
`pub fn hint(&self) -> Option<&'static str>`

### Return Value
- **type**: `Option<&'static str>` - The hint message, or `None` if no hint is available.

### Hint Mapping
- `NotAuthenticated` / `OAuthInvalidGrant(_)` → "Run `railway login` to authenticate, then re-run."
- `OAuthInsufficientGrant` → login again and ensure the integration has access.
- `NoLinkedProject` / `ProjectNotFound` → "Run `railway link` to connect to a project."
- `NoServiceLinked` → "Run `railway service` to link a service."
```
Tokens:
Raw