### Install graphql-client CLI

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

Install the graphql-client CLI tool using cargo. This is a prerequisite for generating the schema.

```sh
cargo install graphql_client_cli
```

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

### Command Registration Macro Examples

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

Provides concrete examples of using the `commands!` macro with various configurations, including single commands, commands with aliases, and commands with custom names.

```rust
commands!(
    add,
    dev(develop),                    // 'railway dev' or 'railway develop'
    environment(env),                // 'railway environment' or 'railway env'
    run(local),                      // 'railway run' or 'railway local'
    sandbox(sandboxes, sbx),        // 'railway sandbox', 'railway sandboxes', 'railway sbx'
    tcp_proxy as "tcp-proxy",       // 'railway tcp-proxy' (not 'tcp_proxy')
    variable(variables, vars, var), // Multiple aliases
);
```

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

### install_method Module

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

Detects how the CLI was installed and provides methods to check update capabilities.

```APIDOC
## InstallMethod::detect() -> Self

### Description
Auto-detects the installation method of the CLI from the current environment. It checks environment variables, binary paths, and package manager metadata.

### Returns
- `InstallMethod` - The detected installation method (e.g., `Npm`, `Homebrew`, `Prebuilt`, `Curl`, `Unknown`).

### Example
```rust
let method = InstallMethod::detect();
match method {
    InstallMethod::Npm => println!("Installed via npm"),
    InstallMethod::Homebrew => println!("Installed via brew"),
    _ => println!("Other installation method"),
}
```
```

```APIDOC
## InstallMethod::can_self_update(&self) -> bool

### Description
Checks if the current installation method supports self-updates. This is typically true for methods like `curl` or pre-built binaries.

### Returns
- `bool` - `true` if self-updates are supported, `false` otherwise.
```

```APIDOC
## InstallMethod::can_write_binary(&self) -> bool

### Description
Determines if the CLI binary location is writable for the current user, which is necessary for self-updates.

### Returns
- `bool` - `true` if the binary location is writable, `false` otherwise.
```

```APIDOC
## InstallMethod::can_auto_run_package_manager(&self) -> bool

### Description
Checks if the package manager associated with the installation method can be automatically run for updates (e.g., npm, brew).

### Returns
- `bool` - `true` if the package manager can be auto-run, `false` otherwise.
```

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

### Manual CLI Commands

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

Examples of manually running common CLI commands for testing purposes.

```bash
cargo run -- login
```

```bash
cargo run -- link
```

```bash
cargo run -- up
```

```bash
cargo run -- logs --follow
```

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

### Start Development Watch

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

Starts a local development mode that watches specified file paths for changes and triggers hot-reloads.

```APIDOC
## Start Development Watch

### Description
Watches local files and hot-reloads on changes.

### Method
POST (inferred)

### Endpoint
/develop/start (inferred)

### Parameters
#### Request Body
- **watch_paths** (array of strings) - Required - Paths to watch for changes.

### Response
#### Success Response (200)
- **message** (string) - Indicates that development mode has started.
```

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

### Detect CLI Installation Method

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

Auto-detects the CLI installation method by checking environment variables, binary paths, and package manager metadata. Falls back to `Unknown` if detection fails.

```rust
pub enum InstallMethod {
    Npm,
    Homebrew,
    Scoop,
    Prebuilt,
    Curl,
    Unknown,
}
```

```rust
let method = InstallMethod::detect();
match method {
    InstallMethod::Npm => println!("Installed via npm"),
    InstallMethod::Homebrew => println!("Installed via brew"),
    _ => println!("Other installation method"),
}
```

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

### Define a Minimal Local Service

Source: https://github.com/railwayapp/cli/blob/master/assets/railway-config/SKILL.md

Configures a local service with build and start commands. Ensure your project has the necessary build and start scripts defined.

```typescript
const web = service("web", {
  build: "bun run build",
  start: "NODE_ENV=production bun src/index.ts",
});
```

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

### Setup Railway Agent Support

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

Configures Railway agent support, installing necessary skills and setting up the MCP server for AI coding tools. Use the '-y' flag to skip interactive prompts.

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

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

### Module Loading Order Example

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

Illustrates the relationship between commands registered in the `commands!` macro and their corresponding module files, showing the expected structure for command implementation.

```rust
commands!(login, dev, environment);

// Requires these files/modules:
src/commands/login.rs      → pub struct Args, pub async fn command
src/commands/dev.rs        → pub struct Args, pub async fn command
src/commands/environment/mod.rs → pub struct Args, pub async fn command
```

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

### Displaying Specific Command Help

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

Illustrates how to get detailed help for a specific command, including its usage, options, and arguments. This is useful for understanding command parameters.

```bash
$ railway deploy --help
Provisions a template into your project

Usage: railway deploy [OPTIONS]

Options:
  -t, --template <TEMPLATE>
          The code of the template to deploy
  
  -v, --variable <VARIABLE>
          The "{key}={value}" environment variable pair
```

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

### Stream Service Logs Subscription

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

This example demonstrates how to establish a WebSocket connection and subscribe to real-time service logs. It requires a WebSocket URL and subscription query variables.

```rust
use reqwest_websocket::*;
use graphql_ws_client::graphql_ws::ConnectionInit;

// 1. Create WebSocket connection
let (wsio, _) = reqwest_websocket::Client::new()
    .connect(ws_url)
    .await?;

// 2. Send subscription request
let sub = graphql_ws_client::Subscription::new(
    queries::service_logs::OPERATION_NAME,
    queries::service_logs::OPERATION,
    vars,
);

// 3. Stream responses
let mut stream = sub.subscribe::<queries::ServiceLogs>(wsio).await?;
while let Some(msg) = stream.next().await {
    println!("{}", msg?.data?.service_logs);
}
```

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

### Initialize Railway CLI Configs

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

Creates or loads the Railway CLI configuration from disk. Use this to get an instance of the Configs manager.

```rust
let configs = Configs::new()?;
```

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

### Combined commands! Macro Usage

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

An example combining basic command registration, aliases, and custom names within a single `commands!` macro invocation.

```rust
commands!(
    login,
    dev(develop),
    environment(env),
    tcp_proxy as "tcp-proxy",
    sandbox(sandboxes, sbx),
);
```

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

### Install Railway CLI with Agent Support

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

Installs the Railway CLI and configures agent support for AI coding tools. This command is suitable for macOS, Linux, and Windows via WSL.

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

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

### Command Structure Example

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

Illustrates the typical structure for a Railway CLI command, including argument parsing with `clap` and an asynchronous command function.

```rust
use clap::Parser;
use anyhow::Result;

#[derive(Parser)]
pub struct Args {
    // Command-specific arguments
}

pub async fn command(args: Args) -> Result<()> {
    // Command implementation
    Ok(())
}
```

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

### Install Railway CLI without Agent Support

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

Installs the Railway CLI without configuring agent support. Use this command if AI coding tool integration is not required.

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

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

### GraphQL Project Query Definition

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

An example of a GraphQL query definition file for fetching project details, including its services and environments. Note the use of variables and pagination arguments.

```graphql
query Project($id: ID!) {
  project(id: $id) {
    id
    name
    description
    createdAt
    updatedAt
    services(first: 100) {
      edges {
        node {
          id
          name
          status
        }
      }
    }
    environments(first: 50) {
      edges {
        node {
          id
          name
          isProduction
        }
      }
    }
  }
}

```

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

### Get Linked Project Configuration

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

Loads configuration and retrieves the currently linked project. Ensure Configs can be initialized.

```rust
let mut configs = Configs::new()?;
let linked = configs.get_linked_project().await?;
let env_id = linked.environment_id()?;
```

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

### Configure Replicas for a Service

Source: https://github.com/railwayapp/cli/blob/master/assets/railway-config/SKILL.md

Sets the number of replicas for a service to enable high availability. This example sets it to 3 replicas.

```typescript
const web = service("web", {
  replicas: 3,
});
```

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

### Async Main Function with Tokio

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

The CLI uses Tokio as its asynchronous runtime. This example shows the basic structure of an async main function.

```rust
#[tokio::main]
async fn main() -> Result<()> {
    // All async code runs here
}
```

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

### Install Specific Railway Agent

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

Installs a specific Railway agent, such as 'cursor'. Use this command when you only need to set up a particular AI coding tool.

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

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

### GraphQL Generated Type Example

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

Illustrates the naming convention for generated GraphQL query structs and their corresponding response types, edges, and nodes.

```rust
// Query struct
pub struct Project;

// In queries::project module:
pub struct ProjectProject { /* fields */ }
pub struct ProjectProjectServicesEdges { /* fields */ }
pub struct ProjectProjectServicesEdgesNode { /* fields */ }
```

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

### Install Specific Railway Skill

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

Installs a specific Railway skill, such as for 'claude-code'. Use this command when you only need to enable a particular AI coding feature.

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

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

### Alias Routing Example

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

The macro handles routing for command aliases, allowing shorter or alternative names to map to the correct command.

```rust
// "railway dev" → dev::command
// "railway develop" → dev::command
// "railway env" → environment::command
// etc.
```

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

### Spawning non-blocking background tasks

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

This example shows how to spawn a non-blocking background task using `tokio::spawn`. This is commonly used for operations like checking for updates or sending telemetry data.

```rust
tokio::spawn(async {
    check_update(false).await.ok();  // Fire and forget
});
```

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

### Get Project Details

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

Fetches project details by its ID. Use this function when you need to retrieve specific project information for further processing.

```rust
let project = get_project(&client, &configs, "proj_123".to_string()).await?;
println!("Services: {}", project.services.edges.len());
```

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

### Get Linked Environment ID

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

Retrieves the linked environment ID from a LinkedProject instance. Returns an error with setup instructions if no environment is linked.

```rust
let env_id = linked_project.environment_id()?;
```

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

### LinkedProject::environment_id()

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

Gets the linked environment ID from a `LinkedProject` object. It returns a `Result<&str>` which is either the environment ID or an error with setup instructions if no environment is linked.

```APIDOC
## LinkedProject::environment_id()

### Description
Gets the linked environment ID, returning an error if none is linked.

### Method
`linked_project.environment_id()`

### Returns
- `Result<&str>` - Environment ID or error with setup instructions
```

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

### Initialize Railway Configuration Files

Source: https://github.com/railwayapp/cli/blob/master/assets/railway-config/README.md

Use this command to create the initial configuration files for your Railway project.

```bash
railway config init
```

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

### Integrating Commands Macro in Main

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

Shows how to integrate the `commands!` macro within `src/main.rs` to register commands and set up the main execution flow using `tokio`.

```rust
commands!(
    login,
    dev(develop),
    environment(env),
    // ...
);

#[tokio::main]
async fn main() -> Result<()> {
    let command = Commands::try_parse()?;
    command.execute().await
}
```

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

### Get Account/Workspace Token from Environment

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

Gets the account or workspace token from the RAILWAY_API_TOKEN environment variable. Use this for account-level operations.

```rust
if let Some(token) = Configs::get_railway_api_token() {
    // Use account-level token
}
```

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

### Execute a Basic GraphQL Project Query

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

Demonstrates how to execute a basic GraphQL query to fetch project details. Ensure you have the necessary configurations and an authorized client.

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

// 1. Create client
let configs = Configs::new()?;
let client = GQLClient::new_authorized(&configs)?;

// 2. Prepare variables
let vars = queries::project::Variables {
    id: "proj_abc123".to_string(),
};

// 3. Execute query
let response = post_graphql::<queries::Project, _>(
    &client,
    configs.get_backboard(),
    vars
)?;

// 4. Extract response
let project = response.project;
println!("Project: {}", project.name);
```

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

### Get Project Access Token from Environment

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

Gets the project access token from the RAILWAY_TOKEN environment variable. Useful for CI/CD or automated processes.

```rust
if let Some(token) = Configs::get_railway_token() {
    // Use project-level token
}
```

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

### workspaces_with_client(client: &Client, configs: &Configs)

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

Fetches workspaces using an existing authenticated client and configurations, avoiding redundant authentication steps.

```APIDOC
## workspaces_with_client(client: &Client, configs: &Configs)

### Description
Fetches workspaces using an existing client (avoids redundant authentication).

### Method
Rust Function

### Parameters
#### Path Parameters
- `client` (`&Client`): Authenticated HTTP client.
- `configs` (`&Configs`): Railway configuration.

### Returns
- `Result<Vec<Workspace>>`: A list of workspaces or an error.

### Example
```rust
let client = GQLClient::new_authorized(&configs)?;
let workspaces = workspaces_with_client(&client, &configs).await?;
```
```

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

### Command Execution Pattern

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

Illustrates the standard structure for a command's implementation file, including argument parsing with `clap` and asynchronous command execution.

```rust
// src/commands/example.rs

use super::*;  // Imports Parser, Result, Configs, etc.

/// Short description of what the command does.
#[derive(Parser)]
pub struct Args {
    /// Help text for argument 1
    #[arg(short, long)]
    pub option1: String,
    
    /// Help text for optional argument
    #[arg(short, long)]
    pub option2: Option<String>,
}

pub async fn command(args: Args) -> Result<()> {
    let configs = Configs::new()?;
    let client = GQLClient::new_authorized(&configs)?;
    
    // ... implementation
    
    Ok(())
}
```

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

### Implement a CLI Command

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

Provides a basic structure for implementing a command-line interface command using the `clap` crate for argument parsing and `async` execution. Initializes configuration and GraphQL client.

```rust
#[derive(Parser)]
pub struct Args {
    #[arg(short, long)]
    pub name: String,
}

pub async fn command(args: Args) -> Result<()> {
    let mut configs = Configs::new()?;
    let client = GQLClient::new_authorized(&configs)?;
    
    // Business logic here
    
    Ok(())
}
```

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

### GraphQL Query for Project Details

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

This is a sample GraphQL query to fetch project details, including its services.

```graphql
query Project($id: ID!) {
  project(id: $id) {
    id
    name
    services(first: 100) {
      edges {
        node {
          id
          name
        }
      }
    }
  }
}
```

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

### Service Controller - Get Latest Deployment

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

Retrieves the most recent deployment for a specified service.

```APIDOC
## get_service_latest_deployment

### Description
Gets the most recent deployment for a service.

### Function Signature
`get_service_latest_deployment(client: &Client, configs: &Configs, service_id: String) -> Result<Deployment>`

### Parameters
- **client** (`&Client`) - Authenticated HTTP client
- **configs** (`&Configs`) - Configuration
- **service_id** (String) - Service ID

### Returns
- `Result<Deployment>` - Latest deployment
```

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

### Get User Info

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

Fetches the information of the currently authenticated user. Requires an authenticated client.

```APIDOC
## Get User Info

### Description
Fetches current authenticated user's info.

### Method
GET

### Endpoint
/user

### Parameters
#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **user** (User) - The user struct containing user information.
```

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

### Basic commands! Macro Usage

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

Demonstrates the basic form of the `commands!` macro, registering a single command module.

```rust
commands!(login);
```

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

### Preview Railway Configuration Changes

Source: https://github.com/railwayapp/cli/blob/master/assets/railway-config/README.md

Generate a plan to preview the changes that Railway would make without applying them.

```bash
railway config plan
```

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

### Variables Controller - Get Service Variables

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

Fetches all environment variables for a given service within a specific environment.

```APIDOC
## get_service_variables

### Description
Fetches all environment variables for a service in an environment.

### Function Signature
`get_service_variables(client: &Client, configs: &Configs, service_id: String, environment_id: String) -> Result<EnvironmentVariables>`

### Parameters
- **client** (`&Client`) - Authenticated HTTP client
- **configs** (`&Configs`) - Configuration
- **service_id** (String) - Service ID
- **environment_id** (String) - Environment ID

### Returns
- `Result<EnvironmentVariables>` - Map of variable name -> value

**Note:** Returns `BTreeMap<String, Option<String>>` where None values indicate unset variables.
```

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

### Get Currently Linked Project

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

Retrieves the project linked to the current directory. Returns an error if no project is linked.

```rust
let linked = configs.get_linked_project().await?;
println!("Project: {}", linked.project);
```

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

### Get Railway Error Code

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

Retrieve a stable, machine-readable error code from a `RailwayError`. This is useful for programmatic error handling.

```rust
match command().await {
    Ok(_) => {},
    Err(e) => {
        if let Some(railway_err) = e.downcast_ref::<RailwayError>() {
            eprintln!("ERROR [{}]: {}", railway_err.code(), railway_err);
        }
    }
}
```

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

### Fetch Workspaces with Existing Client

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

Fetches workspaces using a pre-authenticated HTTP client and configuration. This avoids redundant authentication steps.

```rust
let client = GQLClient::new_authorized(&configs)?;
let workspaces = workspaces_with_client(&client, &configs).await?;
```

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

### Deploy Project using Project Token

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

Deploys a project using an environment variable for authentication. This is suitable for CI/CD pipelines where interactive login is not possible.

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

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

### Get Optional Hint for Railway Error

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

Retrieve an optional actionable hint for a `RailwayError`. This provides guidance to the user on how to resolve the error.

```rust
if let Some(hint) = error.hint() {
    eprintln!("Next step: {}", hint);
}
```

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

### Fetch Project Data via GraphQL

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

Fetches project data using the GraphQL client. Requires an authorized client and project ID. Assumes `post_graphql` and `queries::project` are available.

```rust
let client = GQLClient::new_authorized(&configs)?;
let vars = queries::project::Variables { id: project_id };
let response = post_graphql::<queries::Project, _>(
    &client,
    configs.get_backboard(),
    vars
)?;
let project = response.project;
```

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

### Displaying General CLI Help

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

Shows the general usage and available commands for the Railway CLI. This is typically invoked using the `--help` flag.

```bash
$ railway --help
Usage: railway <COMMAND>

Commands:
  add
  agent
  autoupdate
  bucket
  cdn
  completion
  config
  connect
  delete
  deploy
  deployment
  dev
  docs
  ...
```

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

### Configs::get_railway_api_token()

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

Gets the account/workspace token from the `RAILWAY_API_TOKEN` environment variable. It returns an `Option<String>` containing the token if the environment variable is set.

```APIDOC
## Configs::get_railway_api_token()

### Description
Gets the account/workspace token from the `RAILWAY_API_TOKEN` environment variable.

### Method
`Configs::get_railway_api_token()`

### Returns
- `Option<String>` - Token from `RAILWAY_API_TOKEN` env var if set

### Example
```rust
if let Some(token) = Configs::get_railway_api_token() {
    // Use account-level token
}
```
```

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

### Get Backboard API Endpoint

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

Returns the URL for the GraphQL API endpoint (backboard). This URL may vary between production and staging environments.

```rust
let backboard_url = configs.get_backboard();
```

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

### Pull Existing Railway Project into Code

Source: https://github.com/railwayapp/cli/blob/master/assets/railway-config/README.md

Import an existing Railway project's configuration into code.

```bash
railway config pull
```

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

### commands! Macro with Aliases

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

Shows how to use the `commands!` macro to register a command module with multiple aliases.

```rust
commands!(environment(env), dev(develop), variable(variables, vars, var));
```

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

### Command Registration Macro Syntax

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

Defines the basic syntax for the `commands!` macro, showing how to register modules, aliases, and custom command names.

```rust
commands!(
    module_name,                           // Creates variant Commands::ModuleName
    module_name(alias1, alias2),          // Additional aliases for the command
    long_module_name as "dash-separated", // Custom command name
);
```

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

### Configs::get_railway_token()

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

Gets the project access token from the `RAILWAY_TOKEN` environment variable. It returns an `Option<String>` containing the token if the environment variable is set.

```APIDOC
## Configs::get_railway_token()

### Description
Gets the project access token from the `RAILWAY_TOKEN` environment variable.

### Method
`Configs::get_railway_token()`

### Returns
- `Option<String>` - Token from `RAILWAY_TOKEN` env var if set

### Example
```rust
if let Some(token) = Configs::get_railway_token() {
    // Use project-level token
}
```
```

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

### ExecutionContext Struct

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

A snapshot of the runtime environment and user context, including flags for JSON output, CI mode, TTY status, agent harness detection, and browser reachability.

```APIDOC
## ExecutionContext Struct

### Description
A snapshot of the runtime environment and user context.

### Fields
- **json** (bool): Command was asked for machine-readable output (`--json` flag).
- **ci** (bool): CI mode explicitly requested (`--ci` flag or `CI=true` env var).
- **stdout_tty** (bool): stdout is connected to a terminal (not piped/captured).
- **stdin_tty** (bool): stdin is connected to a terminal (can prompt interactively).
- **agent_harness** (bool): A known agent harness (Claude Code, Cursor, etc.) is driving the CLI.
- **browser_reachable** (bool): A local browser can plausibly open (not in SSH/headless environment).
```

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

### Get User OAuth Token

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

Retrieves the user's OAuth authentication token, used for API requests. Returns None if the user is not logged in.

```rust
if let Some(token) = configs.get_railway_auth_token() {
    println!("User is authenticated");
}
```

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

### Configs::new()

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

Creates or loads the Railway CLI configuration from disk. It returns a `Result<Configs>` which is either the configuration instance or an error if the config directory cannot be read.

```APIDOC
## Configs::new()

### Description
Creates or loads the Railway CLI configuration from disk.

### Method
`Configs::new()`

### Returns
- `Result<Configs>` - Configuration instance, or error if unable to read config directory

### Example
```rust
let configs = Configs::new()?;
```
```

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

### Get Service by Name

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

Finds a specific service within a project's data by its name. Use this when you have the project data and need to locate a particular service.

```rust
let service = get_service(&project_data, "my-service".to_string()).await?;
```

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

### Run Integration Tests

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

Execute end-to-end command tests. These tests are located in the `tests/` directory.

```bash
cargo test --test '*'
```

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

### Configs::get_linked_project()

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

Gets the currently linked project for the current directory. It returns a `Result<LinkedProject>` which is either the linked project details or an error if no project is linked.

```APIDOC
## Configs::get_linked_project()

### Description
Gets the currently linked project for this directory.

### Method
`configs.get_linked_project()`

### Returns
- `Result<LinkedProject>` - The linked project, or error if no project is linked

### Example
```rust
let linked = configs.get_linked_project().await?; 
println!("Project: {}", linked.project);
```
```

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

### Environment Command with Subcommands

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

Demonstrates how the macro supports nested subcommands within a command module using Clap's Subcommand derive.

```rust
// src/commands/environment/mod.rs
#[derive(Parser)]
pub struct Args {
    #[command(subcommand)]
    pub subcommand: Option<Subcommand>,
}

#[derive(Subcommand)]
pub enum Subcommand {
    /// Create a new environment
    New(new::Args),
    
    /// List environments
    List(list::Args),
    
    /// Delete an environment
    Delete(delete::Args),
}
```

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

### Manually Configure Project Link

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

Edit the `~/.railway/config.json` file directly to set project paths, project IDs, and environment IDs.

```json
{
  "projects": {
    "/path/to/project": {
      "projectPath": "/path/to/project",
      "project": "proj_abc123",
      "environment": "env_def456"
    }
  }
}
```

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

### Create Public HTTP Client

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

Creates a public HTTP client for API requests that do not require authentication. Ensure the user-agent header can be set.

```rust
let client = GQLClient::new_public()?;
let response = client.get("https://api.railway.com/...").send().await?;
```

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

### ProjectEnvironmentInstances Struct

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

Represents the running instances (deployments) for services and volumes within a project environment.

```rust
pub struct ProjectEnvironmentInstances {
    pub service_instances: Vec<ProjectServiceInstanceEdge>,
    pub volume_instances: Vec<ProjectVolumeInstanceEdge>,
}
```

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

### Prompt User for Selection

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

Use `prompt_select` to present a list of options to the user and retrieve their choice. This function is useful for scenarios where the user needs to choose from a predefined set of values.

```rust
let workspaces = vec!["prod", "staging", "dev"];
let selected = prompt_select("Select workspace", workspaces)?;
```

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

### Create and Update Progress Spinner

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

Use `create_spinner` to initialize an animated progress indicator with a message. The returned handle can be used to update the spinner's status or mark it as finished.

```rust
let spinner = create_spinner("Deploying...");
// Do work
spinner.finish_with_message("Deployment complete!");
```

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

### prompt_text

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

Prompts the user to enter text input. Returns the entered string.

```APIDOC
## prompt_text

### Description
Prompts the user to enter text input. Returns the entered string.

### Function Signature
`prompt_text(message: &str) -> Result<String>`

### Parameters
#### Path Parameters
- **message** (`&str`) - Required - The prompt text to display to the user

### Returns
- **Result<String>** - The string entered by the user, or an error if the prompt failed.
```

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

### Fetch All Workspaces

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

Retrieves all workspaces accessible to the authenticated user. Handles potential authentication, network, or API errors.

```rust
let workspaces = workspaces().await?;
for workspace in workspaces {
    println!("Workspace: {}", workspace.name());
}
```

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

### Project Query

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

Retrieves details about a specific project, including its services and environments.

```APIDOC
## Query Project

### Description
Retrieves details about a specific project, including its services and environments.

### GraphQL Operation
query Project($id: ID!) 

### Parameters
#### Query Variables
- **id** (ID!) - Required - The unique identifier of the project.

### Request Example
```json
{
  "query": "query Project($id: ID!) {\n  project(id: $id) {\n    id\n    name\n    description\n    createdAt\n    updatedAt\n    services(first: 100) {\n      edges {\n        node {\n          id\n          name\n          status\n        }\n      }\n    }\n    environments(first: 50) {\n      edges {\n        node {\n          id\n          name\n          isProduction\n        }\n      }\n    }\n  }\n}",
  "variables": {
    "id": "proj_123"
  }
}
```

### Response
#### Success Response
- **project** (Project) - Details of the project.
  - **id** (ID) - The project's unique identifier.
  - **name** (String) - The project's name.
  - **description** (String) - The project's description.
  - **createdAt** (DateTime) - The timestamp when the project was created.
  - **updatedAt** (DateTime) - The timestamp when the project was last updated.
  - **services** (ServiceConnection) - A list of services associated with the project.
    - **edges** (ServiceEdge) - A list of service edges.
      - **node** (Service) - The service details.
        - **id** (ID) - The service's unique identifier.
        - **name** (String) - The service's name.
        - **status** (ServiceStatus) - The current status of the service.
  - **environments** (EnvironmentConnection) - A list of environments associated with the project.
    - **edges** (EnvironmentEdge) - A list of environment edges.
      - **node** (Environment) - The environment details.
        - **id** (ID) - The environment's unique identifier.
        - **name** (String) - The environment's name.
        - **isProduction** (Boolean) - Indicates if the environment is the production environment.

### Response Example
```json
{
  "data": {
    "project": {
      "id": "proj_123",
      "name": "My Project",
      "description": "A sample project.",
      "createdAt": "2023-01-01T12:00:00Z",
      "updatedAt": "2023-01-01T12:00:00Z",
      "services": {
        "edges": [
          {
            "node": {
              "id": "srv_abc",
              "name": "Backend Service",
              "status": "RUNNING"
            }
          }
        ]
      },
      "environments": {
        "edges": [
          {
            "node": {
              "id": "env_prod",
              "name": "Production",
              "isProduction": true
            }
          }
        ]
      }
    }
  }
}
```
```

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

### Handling Paginated GraphQL Results

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

Illustrates how to handle paginated data returned from GraphQL queries, typically using edges and nodes. It also shows how to perform cursor-based pagination with `after` and `limit` variables.

```rust
// Query returns edges with nodes
let services = project.services.edges;  // Vec<*Edge>

for edge in services {
    let node = edge.node;  // Actual data
    // use node...
}

// Some queries support cursor-based pagination
let response = post_graphql::<queries::Deployments, _>(
    &client,
    url,
    queries::deployments::Variables {
        service_id: "srv_123".to_string(),
        after: Some("cursor_value".to_string()),  // For pagination
        limit: Some(100),
    }
)?;
```

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

### pick_workspace(workspaces: Vec<Workspace>, requested: Option<String>)

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

Resolves a single workspace from a provided list, supporting optional filtering by ID or name, and auto-selection when applicable.

```APIDOC
## pick_workspace(workspaces: Vec<Workspace>, requested: Option<String>)

### Description
Resolves a single workspace from a list, supporting optional filtering and auto-selection.

### Method
Rust Function

### Parameters
#### Path Parameters
- `workspaces` (`Vec<Workspace>`): Available workspaces.
- `requested` (`Option<String>`): Workspace ID or name to filter (optional).

### Returns
- `Result<Workspace>`: The selected workspace or an error.

### Behavior:
- If `requested` is provided, searches by ID (case-insensitive) then by name.
- If exactly one workspace is available and `requested` is None, auto-selects it.
- If multiple workspaces and no `requested`, prompts user to select (TTY only).
- Non-TTY with multiple workspaces and no `--workspace` flag returns error.

### Throws:
- `RailwayError::WorkspaceNotFound`: `requested` ID/name not found in list.
- `anyhow::Error`: Non-TTY with multiple workspaces requires `--workspace` flag.

### Example
```rust
let workspaces = workspaces().await?;
let workspace = pick_workspace(workspaces, Some("my-workspace".to_string()))?;
println!("Selected: {}", workspace.name());
```
```

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

### prompt_select

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

Prompts the user to select an item from a list of options. Returns the selected item.

```APIDOC
## prompt_select

### Description
Prompts the user to select an item from a list of options. Returns the selected item.

### Function Signature
`prompt_select<T: Display>(message: &str, options: Vec<T>) -> Result<T>`

### Parameters
#### Path Parameters
- **message** (`&str`) - Required - The prompt text to display to the user
- **options** (`Vec<T>`) - Required - A vector of displayable options for the user to choose from

### Returns
- **Result<T>** - The selected item of type T, or an error if the prompt failed.

### Example
```rust
let workspaces = vec!["prod", "staging", "dev"];
let selected = prompt_select("Select workspace", workspaces)?;
```
```

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

### Define a GitHub Service

Source: https://github.com/railwayapp/cli/blob/master/assets/railway-config/SKILL.md

Configures a service using a GitHub repository as the source. Specify the owner/repo and optionally a branch.

```typescript
const web = service("web", {
  source: github("owner/repo", { branch: "main" }),
  build: "pnpm run build",
  start: "pnpm start",
});
```

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

### ensure_project_and_environment_exist

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

Validates the existence of a specified project and its associated environment. If both exist and are accessible, it returns the project data and the environment ID. It can throw errors if the project or environment is deleted or restricted.

```APIDOC
## ensure_project_and_environment_exist

### Description
Validates that a project and environment exist and returns them.

### Method
Not Applicable (Function Call)

### Parameters
#### Path Parameters
- **client** (`&Client`) - Required - Authenticated HTTP client
- **configs** (`&Configs`) - Required - Configuration
- **linked** (`&LinkedProject`) - Required - Linked project config

### Returns
- `Result<(RailwayProject, String)>` - Project and environment ID

### Throws
- `RailwayError::ProjectDeleted` — Project is soft-deleted
- `RailwayError::EnvironmentDeleted` — Environment is soft-deleted
- `RailwayError::EnvironmentRestricted` — Environment has access restrictions
```

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

### compare_semver Module

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

Provides utilities for comparing semantic version strings.

```APIDOC
## compare_semver(current: &str, newer: &str) -> Ordering

### Description
Compares two semantic version strings to determine their order.

### Parameters
#### Query Parameters
- **current** (`&str`) - Required - The current version string (e.g., "5.23.3").
- **newer** (`&str`) - Required - The version string to compare against (e.g., "5.24.0").

### Returns
- `Ordering` - Returns `Ordering::Less`, `Ordering::Equal`, or `Ordering::Greater` based on the comparison.
```

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

### Iterating Through Workspace Projects

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

Demonstrates how to iterate over all non-deleted projects within a workspace and print their names. Ensure the workspace object is available before calling this method.

```rust
for project in workspace.projects() {
    println!("Project: {}", project.name());
}
```

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

### Configure Advanced Service Placement with Replicas

Source: https://github.com/railwayapp/cli/blob/master/assets/railway-config/SKILL.md

Specifies the number of replicas for a service across different regions. This allows for geographically distributed deployments.

```typescript
const web = service("web", {
  replicas: {
    "us-west2": 2,
    "europe-west4": 1,
  },
});
```

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

### Define a Docker Image Service

Source: https://github.com/railwayapp/cli/blob/master/assets/railway-config/SKILL.md

Configures a service using a Docker image. Provide the image name and tag.

```typescript
const worker = service("worker", {
  source: image("ghcr.io/acme/worker:latest"),
});
```

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

### Project Methods

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

Provides methods to retrieve information about a project, including its ID, name, and timestamps for updates and deletions.

```APIDOC
## Project Methods

### Description
Provides methods to retrieve information about a project, including its ID, name, and timestamps for updates and deletions.

### Methods

#### `id(&self) -> &str`

Returns the project's unique ID.

---

#### `name(&self) -> &str`

Returns the project's display name.

---

#### `updated_at(&self) -> DateTime<Utc>`

Returns the last modification timestamp.

---

#### `deleted_at(&self) -> Option<DateTime<Utc>>`

Returns deletion timestamp if the project is soft-deleted, None otherwise.

---
```

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

### Handling GraphQL Errors in Rust

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

Demonstrates how to check for and handle GraphQL errors returned from a query response.

```rust
let response = post_graphql::<queries::Project, _>(...)?;
// If response.errors is Some:
// RailwayError::GraphQLError(message) is returned

// Example errors:
// - "Project not found" → RailwayError::ProjectNotFound
// - "Unauthorized" → RailwayError::Unauthorized
// - Other messages → RailwayError::GraphQLError(msg)
```

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

### Create User Authorized HTTP Client

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

Creates an authenticated client that specifically requires a user OAuth token, not a project token. This is used for user-specific operations.

```rust
let client = GQLClient::new_user_authorized(&configs)?;
// For user-specific operations (whoami, account settings)
```

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

### Configure Custom Domains for a Service

Source: https://github.com/railwayapp/cli/blob/master/assets/railway-config/SKILL.md

Assigns custom domain names to a service. Ensure these domains are properly configured in your DNS settings.

```typescript
const web = service("web", {
  domains: ["app.example.com"],
});
```

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

### Link Local Project to Railway

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

Run this command in your project directory to link it to a Railway project. It prompts for workspace, project, and environment selection.

```bash
cd /path/to/project
railway link
# Select workspace → select/create project → select environment
```