Skip to main content

Documentation Index

Fetch the complete documentation index at: https://superflag.sh/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
CLI Commands Reference

Complete reference for all available commands in the Superflag CLI.
Using Claude Code? Check out the Claude Code skill for AI-powered flag management.

​
Quick Commands

Optimized for automation and AI agents with minimal output.

​
use

Set default app and environment context. 
superflag use <app> <env>
Example: 
superflag use my-app production
# Output: ✓ Context set to my-app/production
Context is saved to ~/.superflag/context.json and used by get and set commands.

​
get

Get a flag value using saved context. 
superflag get <key>
Example: 
superflag get dark-mode
# Output: true
Requires context to be set with superflag use.

​
set

Set a flag value using saved context. 
superflag set <key> <value>
Example: 
superflag set dark-mode false
# Output: ✓
Requires context to be set with superflag use.

​
config

Dump full config as JSON. 
superflag config
Example: 
superflag config
# Output: {"flags":{"dark-mode":{"type":"bool","value":true}},...}
Useful for debugging or piping to other tools.

​
Authentication Commands

​
login

Log in to your Superflag account. 
superflag login
Opens browser for OAuth authentication.

​
logout

Log out and clear credentials. 
superflag logout

​
whoami

Show current user. 
superflag whoami
# Output: Logged in as: you@example.com

​
status

Show authentication and context status. 
superflag status
# Output:
# Auth: Logged in as you@example.com
# Context: my-app/production

​
App Management

​
apps list

List all your apps. 
superflag apps list

​
apps create

Create a new app. 
superflag apps create <name>
Example: 
superflag apps create my-new-app

​
Environment Management

​
envs list

List environments for an app. 
superflag envs list --app <name>
Example: 
superflag envs list --app my-app

​
Flag Management

​
flags list

List all flags in an environment. 
superflag flags list --app <app> --env <env>
Example: 
superflag flags list --app my-app --env production

​
flags create

Create a new flag. 
superflag flags create --app <app> --env <env> --key <key> --type <type> --value <value>
Types: bool, string, number, json Example: 
superflag flags create \
  --app my-app \
  --env production \
  --key new-feature \
  --type bool \
  --value true

​
flags set

Set a flag value. 
superflag flags set --app <app> --env <env> --key <key> --value <value>
Example: 
superflag flags set \
  --app my-app \
  --env production \
  --key dark-mode \
  --value false

​
flags toggle

Toggle a boolean flag. 
superflag flags toggle --app <app> --env <env> --key <key>
Example: 
superflag flags toggle \
  --app my-app \
  --env production \
  --key beta-features

​
flags delete

Delete a flag. 
superflag flags delete --app <app> --env <env> --key <key>
Example: 
superflag flags delete \
  --app my-app \
  --env production \
  --key old-feature

​
flags upsert

Create or update a flag (idempotent). 
superflag flags upsert --key <key> --type <type> --value <value>
Example: 
# Uses context from `superflag use`
superflag flags upsert \
  --key api-url \
  --type string \
  --value https://api.example.com

​
flags bulk-set

Set multiple flags from a JSON file. 
superflag flags bulk-set [--file <path>]
JSON Format: 
{
  "dark-mode": true,
  "api-url": "https://api.example.com",
  "max-retries": 3
}
Example: 
superflag flags bulk-set --file flags.json
If --file is not provided, reads from stdin: 
echo '{"dark-mode": true}' | superflag flags bulk-set

​
flags rollout

Configure gradual rollout percentage for a flag. 
superflag flags rollout --key <key> --percentage <0-100> [--remove]
Options:
  • --percentage: Percentage of users to show the flag value (0-100, decimals allowed)
  • --remove: Remove rollout configuration
Example: 
# Set context first
superflag use my-app production

# Roll out to 25% of users
superflag flags rollout --key new-checkout --percentage 25

# Increase to 50%
superflag flags rollout --key new-checkout --percentage 50

# Remove rollout (back to 100% for all users)
superflag flags rollout --key new-checkout --remove
How it works:
  • Users are deterministically assigned based on their userId (passed to SDK)
  • Same user always gets same result (consistent bucketing)
  • Users not in rollout see the type’s default value (false, "", 0, )

​
flags variants

Configure A/B testing variants for a flag. 
superflag flags variants --key <key> --variant <value:weight:name> [--remove]
Options:
  • --variant: Variant definition in format value:weight:name (can be repeated)
  • --remove: Remove all variants
Example: 
# Set context first
superflag use my-app production

# Create A/B test with 3 variants (50/30/20 split)
superflag flags variants --key button-color \
  --variant "blue:50:control" \
  --variant "green:30:variant-a" \
  --variant "red:20:variant-b"

# Two-way split
superflag flags variants --key pricing-page \
  --variant "monthly:50:control" \
  --variant "annual:50:variant-a"

# Remove variants
superflag flags variants --key button-color --remove
Rules:
  • Weights must sum to 100
  • All variant values must match the flag’s type
  • Users are deterministically assigned (consistent bucketing)
  • Cannot have both rollout and variants on the same flag

​
Key Management

​
keys list

List API keys for an environment. 
superflag keys list --app <app> --env <env>

​
keys create

Create a new API key. 
superflag keys create --app <app> --env <env> --type <type>
Types: sdk, pub Example: 
superflag keys create \
  --app my-app \
  --env production \
  --type pub

​
keys revoke

Revoke an API key. 
superflag keys revoke <key-id>

​
Options

​
Global Options

Available on all commands:
OptionDescription
--help, -hShow help
--version, -vShow version

​
Exit Codes

CodeMeaning
0Success
1Error
2Not authenticated
3Not found

​
Examples

​
Set up a new project

# Log in
superflag login

# Create app
superflag apps create my-project

# Set context
superflag use my-project production

# Create flags
superflag flags upsert --key dark-mode --type bool --value false
superflag flags upsert --key api-url --type string --value https://api.example.com

# Get flag value
superflag get dark-mode

​
Update flags in automation

# Set context once
superflag use my-app staging

# Quick updates
superflag set feature-a true
superflag set feature-b false

# Or bulk update
cat > flags.json <<EOF
{
  "feature-a": true,
  "feature-b": false,
  "api-timeout": 30
}
EOF
superflag flags bulk-set --file flags.json

​
Gradual rollout workflow

# Set context
superflag use my-app production

# Create flag
superflag flags upsert --key new-ui --type bool --value true

# Start with 10% rollout
superflag flags rollout --key new-ui --percentage 10

# Monitor metrics, then increase gradually
superflag flags rollout --key new-ui --percentage 25
superflag flags rollout --key new-ui --percentage 50
superflag flags rollout --key new-ui --percentage 100

# Remove rollout config (now 100% for everyone)
superflag flags rollout --key new-ui --remove

​
A/B testing workflow

# Set context
superflag use my-app production

# Create flag
superflag flags upsert --key cta-text --type string --value "Get Started"

# Configure variants
superflag flags variants --key cta-text \
  --variant "Get Started:33:control" \
  --variant "Start Free Trial:33:variant-a" \
  --variant "Try It Now:34:variant-b"

# Check results in your analytics
# Then remove variants and set winner
superflag flags variants --key cta-text --remove
superflag set cta-text "Try It Now"

​
Next Steps

CI/CD Usage

Use the CLI in automation

Installation

Install and update the CLI