railway flag

Create, inspect, and target feature flags for a project.

Usage

railway flag <COMMAND> [OPTIONS]

Subcommands

Target a project

Create a project token from the tokens page in your project settings, then set it as RAILWAY_TOKEN:

export RAILWAY_TOKEN=<project-token>
railway flag list

The CLI automatically uses the project that owns the token. You don't need to run railway link, set RAILWAY_PROJECT_ID, or pass --scope.

When you authenticate through railway login instead, run railway link once. The CLI uses the linked project for subsequent railway flag commands.

With user authentication, pass --scope project:<project-id> only to override the locally linked project. You can also set the override with RAILWAY_FLAGS_SCOPE=project:<project-id>. A project token remains limited to the project that owns it.

Examples

List flags

railway flag list

Add --full to show rule IDs and empty rule sections.

Set a flag's default

The type is inferred from the value: true or false becomes bool, a number becomes number, valid JSON becomes json, and anything else becomes string.

railway flag set checkout.v2 true
railway flag set theme "blue"
railway flag set api-rate-limit 100
railway flag set model-config '{"name":"small","temperature":0.2}'

Pass --type to set the type explicitly. Changing an existing flag's type clears its rules and requires --force --type <type>.

Attach a targeting rule

--when adds a rule that serves the value when its condition matches, instead of changing the default. The flag must already exist.

railway flag set checkout.v2 true --when 'plan == "enterprise"'
railway flag set checkout.v2 true --when "bucket(key) < 0.25"

Rules are keyed by --rule-id. Reuse an ID to replace a rule. Omit it and the CLI derives a stable ID from the name and expression.

Roll out to a percentage of a segment

Combine conditions with && and || in a single rule. This serves true to 25% of enterprise users:

railway flag set checkout.v2 true \
  --when 'plan == "enterprise" && bucket(key) < 0.25'

Remove a rule

railway flag unset checkout.v2 --rule-id enterprise-on

Delete a flag

railway flag delete checkout.v2

Targeting expressions

--when takes a CEL-style expression or raw JSON.

Comparison operators are ==, !=, <, <=, >, >=, contains, and matches. Bucket thresholds are between 0 and 1, so < 0.25 is 25%. Target rules on the attributes your app passes in the evaluation context, like plan or region. The bucket attribute is the stable key each subject is hashed on, typically the key in that context.

Options

Global options

Options for

Options for

Options for

Options for

Related

• Feature flags
• railway setup