Railway CLI

Railway CLI cheatsheet — deploy apps, view logs, manage env vars, run commands. railway up, railway logs, railway run, railway variables set. Full Railway CLI reference.

6 min read

What it is

The Railway CLI is your command-line interface for managing your Railway deployments, allowing you to deploy code, view logs, and interact with your services from your terminal.

Installation

Linux / macOS:

curl -fsSL https://railway.app/install.sh | bash

Windows (PowerShell):

irm https://railway.app/install.sh | iex

Verification:

railway --version

Core Concepts

Project: A collection of services and variables that represent your application on Railway.
Environment: A specific deployment of your project, often representing different stages like development, staging, or production. Each environment has its own set of deployed services and variables.
Service: A deployable unit within a project (e.g., a web server, a database).
Deployment: A specific version of a service that has been built and deployed to an environment.
Variables: Environment variables that can be set at the project or environment level, used to configure your services.

Commands / Usage

Project & Environment Management

Initialize Railway in a directory:
```
railway init
```
Prompts you to select an existing project and environment, or create a new one, and links the current directory to it.
Link the current directory to a Railway project:
```
railway link
```
Similar to railway init, but specifically for linking an existing directory to a project.
List available projects:
```
railway projects
```
Displays a list of projects you have access to.
List available environments for the current project:
```
railway environments
```
Shows the environments linked to the currently configured project.
Switch the current project:
```
railway project set <project-id-or-name>
```
Sets the active project for subsequent CLI commands.
Switch the current environment:
```
railway env set <environment-id-or-name>
```
Sets the active environment for subsequent CLI commands.

Deployment

Deploy from the current directory:
```
railway up
```
Builds and deploys your project to the current environment. This is the most common command for deploying code changes.
Deploy a specific service:
```
railway up --service my-web-service
```
Deploys only the specified service, triggering a build and redeploy for it.
Force a redeploy of all services:
```
railway up --rerun
```
Forces a rebuild and redeploy of all services, even if no code changes are detected.
Deploy with specific build arguments:
```
railway up --build-arg MY_BUILD_VAR=some_value
```
Passes build-time arguments to the Docker build process.
Deploy and only build, not deploy:
```
railway up --build-only
```
Builds the project’s images but does not deploy them. Useful for debugging build issues.
Deploy to a specific environment (not the current one):
```
railway up --environment production
```
Deploys the project to the 'production' environment, regardless of the currently set environment.

Logs

View logs for all services in the current environment:
```
railway logs
```
Streams logs from all deployed services in real-time.
View logs for a specific service:
```
railway logs --service my-api
```
Streams logs only from the 'my-api' service.
View historical logs:
```
railway logs --prev
```
Shows logs from the previous deployment.
View logs for a specific deployment ID:
```
railway logs --deployment <deployment-id>
```
Fetches logs for a particular deployment.
Follow logs for a specific service:
```
railway logs --service my-worker --follow
```
Continuously streams logs for the 'my-worker' service.

Service Management

List services in the current project/environment:
```
railway services
```
Displays all services configured for the project.
View details of a specific service:
```
railway services show my-database
```
Provides detailed information about the 'my-database' service.
Open a service’s deployment in the web UI:
```
railway services open my-frontend
```
Opens the 'my-frontend' service’s deployment page in your browser.

Variables

List all variables for the current project/environment:
```
railway variables
```
Shows all environment variables set at the project and environment levels.
Set a project-level variable:
```
railway variables set --project MY_PROJECT_VAR=project_value
```
Sets or updates a variable that applies to all environments in the project.
Set an environment-level variable:
```
railway variables set --environment MY_ENV_VAR=env_value
```
Sets or updates a variable specific to the current environment.
Unset a variable:
```
railway variables unset MY_VAR
```
Removes a variable from the current environment.
Unset a project-level variable:
```
railway variables unset --project MY_PROJECT_VAR
```
Removes a project-level variable.

Database Access

Connect to a database service:
```
railway connect my-postgres-db
```
Establishes a direct connection to the specified database service, providing connection details and often launching a client.
Execute a command on a service:
```
railway run my-app -- python manage.py migrate
```
Runs a specific command within the context of the 'my-app' service in the current environment.

Status and Health

Get the status of deployments:
```
railway status
```
Shows the current status of all services and deployments in the active environment.
Check the health of services:
```
railway health
```
Reports on the health status of your deployed services.

Other Commands

View your Railway account information:
```
railway account
```
Displays information about your current Railway account.
View the Railway CLI configuration:
```
railway config
```
Shows the current configuration of the Railway CLI.
Generate a new SSH key for deployment:
```
railway generate ssh-key
```
Creates a new SSH key pair and adds the public key to your Railway account.
Show the latest deployment ID:
```
railway deploy --latest
```
Prints the ID of the most recent deployment.

Common Patterns

Deploying and then watching logs:
```
railway up && railway logs
```
Deploys your changes and then immediately tails the logs for all services.
Deploying a specific service and watching its logs:
```
railway up --service my-api && railway logs --service my-api
```
Deploys only the 'my-api' service and then tails its specific logs.
Running database migrations:
```
railway up --service my-backend && railway run my-backend -- python manage.py migrate
```
First, deploy your backend service, then run database migrations within that service’s environment.
Connecting to a database and running a query (e.g., with psql):
```
railway connect my-postgres-db -- psql -c "SELECT * FROM users;"
```
Connects to the 'my-postgres-db' service and executes a single SQL command.
Setting a production-only variable:
```
railway env set production && railway variables set --environment DATABASE_URL=postgres://user:pass@host:port/db
```
Switches to the 'production' environment and then sets a sensitive environment variable.
Troubleshooting a failed deployment by checking logs:
```
railway status # Identify the failed service
railway logs --service <failed-service-name>
```
First, check the overall status to find the problem, then dive into the logs of the specific failing service.

Gotchas

Current Directory Matters: Most commands (railway up, railway logs, railway init) operate based on the current working directory. Ensure you are in the correct project directory or have linked it properly.
Environment Context: Commands like railway up and railway logs operate on the currently active environment. Use railway env set <env-name> to switch environments before performing actions.
Variable Precedence: Project-level variables are overridden by environment-level variables with the same name.
railway connect vs. Direct Access: railway connect provides a secure tunnel. For direct access outside of the CLI, you’ll need to configure your service to be publicly accessible or use other methods outlined in Railway’s documentation.
Build Context: The railway up command uses the current directory as the build context by default. If your Dockerfile is not at the root or requires specific files, ensure your project structure and railway.toml (if used) are configured correctly.
Service Names: When using flags like --service or commands like railway run, ensure you are using the exact service name as defined in your Railway project.