Using the CLI

The Railway Command Line Interface (CLI) lets you interact with your Railway project from the command line.

Installing the CLI

The Railway CLI can be installed via Homebrew, npm, Scoop, or directly from the source.

Homebrew (macOS)

In a Terminal, enter the following command:

brew install railway

Shell Script (macOS, Linux, Windows via WSL)

In a Terminal, enter the following command:

bash <(curl -fsSL cli.new)

On Windows, you should use Windows Subsystem for Linux with a Bash shell.

Scoop (Windows)

In a PowerShell terminal, enter the following command:

scoop install railway

This installs a native Windows binary (.exe). To learn more about Scoop, see https://scoop.sh/.

Pre-built Binaries

We publish pre-built binaries on our GitHub repository that you can download and use directly.

From Source

The Railway CLI is an open source project on GitHub. You can build a binary from source if you wish.

Authenticating With the CLI

Before you can use the Railway CLI, you must authenticate the CLI to your Railway account:

railway login

This command opens a new tab in your default browser to the https://railway.com authentication page. Follow the instructions to complete the authentication process.

You can also authenticate manually using a Pairing Code. This can be useful if you're authenticating the CLI inside an environment without a browser (e.g. SSH sessions).

Use the --browserless flag to authenticate manually:

railway login --browserless

In situations where user input or interaction isn't possible, such as in CI/CD pipelines, you can set either the RAILWAY_TOKEN or RAILWAY_API_TOKEN environment variable, based on your specific requirements as detailed below.

A Project Token is set via the RAILWAY_TOKEN environment variable.

An Account or Team Token is set via the RAILWAY_API_TOKEN environment variable.

Note: You can only use one type of token at a time. If both are set, the RAILWAY_TOKEN variable will take precedence.

Project Tokens

You can use Project Tokens to authenticate project-level actions.

Project Tokens allow the CLI to access all the project-level actions in the environment set when the token was created.

Some actions you can perform with a project token include -

Deploying code - railway up
Redeploying a deployment - railway redeploy
Viewing build and deployment logs - railway logs

Some actions you cannot perform with a project token include -

Creating a new project - railway init
Printing information about the user - railway whoami
Linking to another workspace - railway link

Use the token by setting the RAILWAY_TOKEN environment variable and then running railway <command>.

RAILWAY_TOKEN=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX railway up

Account Tokens

Account Tokens come in two types - Personal Account Tokens and Team Tokens.

You can use Account Tokens to authenticate all CLI actions across all workspaces.

However, you can only use Team tokens to authenticate actions on projects within the workspace the token was scoped to when it was created.

Some actions you can perform with a personal account token include -

Creating a new project - railway init
Printing information about the user - railway whoami

Some actions you cannot perform with Team Token include -

Printing information about the user - railway whoami
Linking to another workspace - railway link

Use the token by setting the RAILWAY_API_TOKEN environment variable and then running railway <command>.

RAILWAY_API_TOKEN=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX railway whoami

Common Examples of CLI Usage

Below are some of the most commonly used CLI commands. Find a complete list of CLI commands in the CLI API reference page.

Link to a Project

To associate a project and environment with your current directory:

# Link to a project
railway link

This prompts you to select a team, project, and environment to associate with your current directory. Any future commands will be run against this project and environment.

Link to a Service

Associate a service in a project and environment with your current directory:

# Link to a service
railway service

This links your current directory with the chosen service.

Create a Project

Create a new project directly from the command line.

# Create a new project
railway init

This prompts you to name your project and select a team to create the project in.

Local Development

Run code locally with the same environment variables as your Railway project.

# Run <cmd> locally with the same environment variables as your Railway project
railway run <cmd>

For example, to run your Node.js project with your remote environment variables:

# Run your Node.js project with your remote environment variables
railway run npm start

Local Shell

Open a new local shell with Railway environment variables. Similar to railway run but opens a new shell.

# Open a new shell with Railway environment variables
railway shell

Environments

Projects might have multiple environments, but by default the CLI links to the production environment. You can change the linked environment with the environment command.

# Change the linked environment
railway environment

Deploy

Deploy the linked project directory (if running from a subdirectory, the project root is still deployed).

# Show build logs
railway up

# Return immediately after uploading
railway up --detach

If there are multiple services within your project, the CLI will prompt you for a service to deploy to.

Add Database Service

Provision database services for a project.

railway add

Prompts you to select one or more databases to provision for your project.

Logout

railway logout

SSH

The Railway CLI enables you to start a shell session inside your deployed Railway services. This command is useful for:

Debugging and development: Live debugging production issues, running ad-hoc commands, accessing language REPLs, and comparing environments to identify discrepancies.
Database operations: Executing migrations and rollbacks, running recovery operations, importing database dumps, and managing job queues.
System administration: Inspecting log files, monitoring service status, examining file systems, troubleshooting network issues, and modifying application-level configurations within the container.
Framework-specific tasks: Accessing Rails console, Django shell, or NestJS CLI for model inspection, database queries, and large-scale data operations.
Content and asset management: Verifying asset deployment, debugging file uploads, and troubleshooting static asset issues.

Note that this command differs from railway run and railway shell, which pull environment variables and execute commands locally

Prerequisites

Ensure you have the necessary setup in place:

The Railway CLI installed on your local machine.
Logged in with your Railway account using railway login.

Usage

You can copy the exact command directly from the Railway dashboard:

Navigate to your project in the Railway dashboard.
Right-click on the service you want to connect to.
Select "Copy SSH Command" from the dropdown menu.

This generates a complete command with all necessary IDs. Here’s an example

railway ssh --project=de609d2a-d70b-4457-8cb2-f1ce1410f779 --environment=f5bdd2a8-e2d1-4405-b814-eaa24fb9f7e8 --service=3ba723f0-5a20-44e1-9cff-7acd021d0a45

This command establishes a shell session with your running service container. You'll be dropped into either /bin/bash or /bin/sh, depending on what's available in your container.

Alternatively, you can run railway link, followed by railway ssh to achieve the same result.

The CLI also supports single command execution. This enables you to run commands and get their output instantly and exit without staying in an interactive session. Here's an example:

railway ssh -- ls

How it works

Railway SSH differs significantly from traditional SSH implementations. Understanding how it works helps explain its capabilities and limitations.

Railway SSH does not use the standard SSH protocol (sshd). Instead, it establishes connections via a custom protocol built on top of websockets.

This approach provides several advantages:

No need to configure SSH daemons in your containers.
Secure communication through Railway's existing authentication.
Works with any container that has a shell available.

This approach is secure by design:

No SSH daemon exposed publicly on your containers.
All communication goes through Railway's authenticated infrastructure.
Services remain isolated from direct internet access.
Uses Railway's existing security and access control mechanisms.

Limitations and Workarounds

Understanding Railway SSH's limitations helps you plan appropriate workflows and implement effective workarounds for tasks that aren't directly supported.

File Transfer Limitations

Railway SSH does not support traditional file transfer methods:

No SCP (Secure Copy Protocol) support for copying files between local and remote systems.
No sFTP (SSH File Transfer Protocol) functionality for file management.
No direct file download/upload capabilities through the SSH connection.

File transfer workarounds

Connect volume to file explorer service: Deploy a simple file browser service that mounts the same volume as your main application. This provides web-based access to your files for download and upload operations.
Use CURL for file uploads: From within the SSH session, upload files to external services:

# Upload file to a temporary file sharing service
curl -X POST -F "file=@database_dump.sql" https://file.io/

# Upload to cloud storage (example with AWS S3)
aws s3 cp database_dump.sql s3://your-bucket/backups/

# Upload via HTTP to your own endpoint
curl -X POST -F "[email protected]" https://your-app.com/admin/upload

Create temporary secure endpoints: Modify your application to include a temporary, secured endpoint that serves specific files for download:

// Express.js example
app.get('/admin/download/:filename', authenticateAdmin, (req, res) => {
  const filename = req.params.filename;
  const filePath = path.join('/app/data', filename);
  res.download(filePath);
});

SSH Protocol Limitations

Railway SSH does not implement the standard SSH protocol, which means:

No SSH tunneling: Cannot create secure tunnels to access private services or databases through the SSH connection.
No port forwarding: Cannot forward ports from the remote container to your local machine for accessing internal services.
No IDE integration: Cannot use VS Code's Remote-SSH extension or similar tools that depend on the SSH protocol for remote development.

For private service access: Use Tailscale subnet router to create secure network access to your Railway services without exposing them publicly.

Container and Image Limitations

Scratch images: Containers built from scratch images typically don't include shell programs (/bin/bash or /bin/sh), making SSH connections impossible. These minimal images are designed for security and size optimization but sacrifice interactive access.
Minimal containers: Some optimized container images may not include common debugging tools, text editors, or system utilities that you might expect in a traditional server environment.

Troubleshooting

When Railway SSH connections fail or behave unexpectedly, several common issues and solutions can help resolve the problems.

The service must be actively running for SSH connections to work. If your service is configured with "serverless mode" and has gone to sleep, you'll need to wake it up by sending a request before attempting to SSH.
Firewall or network restrictions: Corporate networks or restrictive firewalls may block WebSocket connections used by Railway SSH.

Best Practices

Use SSH for debugging only: Avoid making permanent changes through SSH sessions. Instead, implement changes in your application code and deploy them properly.
Limit sensitive operations: While SSH provides powerful access, avoid storing sensitive data or credentials in ways that might be exposed during SSH sessions.
Monitor SSH usage: Regularly review who has SSH access to your services and ensure permissions align with current team structure and responsibilities. Note that SSH usage is currently not displayed in the dashboard’s Activity tab.
Temporary access patterns: Consider SSH access for debugging and investigation rather than routine administrative tasks, which should be automated through proper deployment processes.