DOCSEARCHbyAlgolia
Submit Docs

Railway CLI

repository·master·Indexed 20 days ago

https://github.com/railwayapp/cli

Command-line interface for interacting with Railway projects. Features include Infrastructure as Code (IaC) management via .railway/railway.ts, S3-compatible bucket management, and integration with AI coding tools through the Railway Agent and MCP server. Supports authentication for interactive and CI/CD environments, automatic updates, and infrastructure planning and application workflows.

Tokens
27.8K
Snippets
115
Records
145
Agent score
68%

What's inside railwayapp-cli

  1. Manage Railway infrastructure with Infrastructure as Code (IaC)

    master

    Railway infrastructure is defined in code using the .railway/railway.ts file. This file allows you to describe your entire Railway project, including services, databases, buckets, custom domains, replicas, groups, and environment variables. This approach enables version-controlled infrastructure management.

    // .railway/railway.ts
// Use this file to describe services, databases, buckets, etc.

  2. Configure scaling, organization, and migration in Railway IaC

    master

    When defining your infrastructure in .railway/railway.ts, keep these configuration patterns in mind:

    • Scaling: Use replicas to scale services. You can still specify specific region names for advanced placement.
    • Organization: Use group("Name", [resources]) to organize large projects into logical groups on the Railway canvas.
    • Migration: If you have services currently managed by a railway.json file, you must migrate them before they can be managed via .railway/railway.ts.

  3. Initialize or import Railway configuration

    master

    You can start managing your infrastructure via code using the following commands:

    • Initialize a new configuration: Create the necessary configuration files for a new project.
    • Import an existing project: Pull your current Railway project settings into a .railway/railway.ts file.

    Note: When importing an existing project, secrets are rendered using preserve() to ensure existing values are retained without writing the actual secret values to your source code. To perform a smaller import that excludes these preserved variables, use the --omit-preserved-variables flag.

    # Create the configuration files
railway config init

# Import an existing Railway project into code
railway config pull

# Import without including preserved secret variables
railway config pull --omit-preserved-variables

  4. Plan and apply infrastructure changes

    master

    To deploy changes to your infrastructure, use a two-step workflow of planning and applying:

    1. Plan: Run railway config plan to preview what changes Railway would make. This command is safe and does not modify your live infrastructure.
    2. Apply: Run railway config apply to execute the changes.

    Important Safety Notes:

    • railway config apply will preview changes and prompt for confirmation before proceeding unless you provide the --yes flag.
    • In non-interactive environments (like CI/CD or agent sessions), if your changes are destructive, you must use railway config apply --confirm-destructive after reviewing the plan.
    # Preview what Railway would change
railway config plan

# Apply the planned changes (with confirmation prompt)
railway config apply

# Apply changes automatically without confirmation
railway config apply --yes

# Apply destructive changes in non-interactive sessions
railway config apply --confirm-destructive

  7. Configure Railway Agent Setup for AI tools

    master

    Railway provides agent support to integrate with AI coding tools (such as Claude Code, Cursor, Codex, OpenCode, GitHub Copilot, and Factory Droid). This setup installs Railway skills and configures the Railway MCP server.

    To run the full setup automatically, use: railway setup agent -y

    Alternatively, you can install specific components:

    • Use railway mcp install --agent <agent-name> to install the MCP server for a specific agent.
    • Use railway skills --agent <agent-name> to manage skills for a specific agent.
    # Full setup
railway setup agent -y

# Focused setup examples
railway mcp install --agent cursor
railway skills --agent claude-code

  8. Authenticate with Railway

    master

    To use the CLI, you must first authenticate with your Railway account.

    For standard interactive sessions, use railway login.

    If you are in an environment without a web browser (such as an SSH session), use the --browserless flag.

    # Standard login
railway login

# Browserless login for SSH/headless environments
railway login --browserless

  9. Install the Railway CLI

    master

    You can install the Railway CLI on macOS, Linux, or Windows (via WSL) using a shell script.

    To install the CLI with automatic agent support configuration (which runs railway setup agent for detected tools), use the --agents flag. The CLI is installed to ~/.railway/bin.

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

  10. Manage Railway templates via CLI

    master

    The railway templates command suite allows you to discover, create, publish, and manage templates in the Railway marketplace. You can interact with these commands in an interactive TTY mode or use the --json flag for automation and machine-readable output.

    Common Subcommands:

    • search (or find): Discover published templates.
    • list (or ls): List templates owned by a workspace.
    • create (or generate): Create an unpublished template draft from an existing project.
    • publish (or update): Publish a new template or update metadata for an existing one.
    • unpublish: Remove a template from the marketplace.
    • delete (or remove, rm): Permanently delete a template draft or marketplace template.
    railway templates search postgres --json
railway templates list --workspace my-workspace --json
railway templates create --project project-id --environment production --json
railway templates publish template-id --category Other --description "My App" --readme-file README.md --json

  11. Manage Railway volumes

    master

    The railway volume command allows you to manage persistent storage volumes within your Railway project. You can list, create, delete, update, attach, and detach volumes, as well as manage files within them via the files subcommand.

    Common Flags

    • --service <SERVICE_ID>: Specify the service to operate on.
    • --environment <ENVIRONMENT_ID>: Specify the environment.
    • -p, --project <PROJECT_ID>: Specify the project ID (defaults to the linked project).

    Aliases

    • list $\rightarrow$ ls
    • add $\rightarrow$ create, new
    • delete $\rightarrow$ remove, rm
    • update $\rightarrow$ edit, rename
    • browse $\rightarrow$ browser
    • files $\rightarrow$ file

    Automation Notes

    • Mount Paths: Must start with /.
    • Volume Selection: Use volume IDs from railway volume list --json when names might collide.
    • Non-interactive mode: Use --json for machine-readable output and --yes to skip confirmation prompts. For file operations, use --overwrite or --override to handle existing paths.
    railway volume list --json
railway volume add --service api --mount-path /data --json
railway volume update --volume volume-id --name data --json
railway volume delete --volume data --yes --json
railway volume browse /
railway volume files list / --json
railway volume files download /backup.tar ./backup.tar --json

  12. Set up local HTTPS with `mkcert`

    master

    Railway CLI can provide local HTTPS support for your development environment.

    Requirements:

    • mkcert must be installed on your system.
    • For full support, run mkcert -install to trust the local CA.

    Behavior:

    • If mkcert is found, the CLI sets up a Caddy proxy and generates wildcard certificates for your local domain (e.g., *.your-project.railway.dev).
    • If port 443 is already in use by another process, the CLI falls back to using per-service ports for HTTP/HTTPS access.