@superflag-sh/cli

Command-line interface for managing Superflag feature flags and remote config.

Quick Start

# Install globally
npm install -g @superflag-sh/cli

# Authenticate
superflag login

# Set your default app and environment
superflag use myapp production

# Get and set flags
superflag get dark-mode
superflag set dark-mode true

Authentication

The CLI uses browser-based OAuth authentication:

superflag login   # Opens browser to authenticate
superflag whoami  # Show current user
superflag logout  # Clear credentials

Credentials are stored in ~/.superflag/credentials.json.

Context System

Instead of passing --app and --env with every command, set a default context:

superflag use myapp staging

This saves your context to ~/.superflag/context.json. Quick commands like get, set, and config will use this context automatically.

You can override context for a single command:

superflag get feature-x --app other-app --env prod

Check your current context with:

superflag status

Commands

Quick Commands

These commands use your saved context for fast flag operations:

superflag use <app> <env>   # Set default app/env context
superflag get <key>         # Get a flag value
superflag set <key> <value> # Set a flag value
superflag config            # Dump full config as JSON
superflag status            # Show auth and context status

Auth Commands

superflag login    # Authenticate via browser
superflag logout   # Clear credentials and context
superflag whoami   # Show current user email

Apps

superflag apps list              # List all your apps
superflag apps create <name>     # Create a new app

Environments

superflag envs list --app <name>  # List environments for an app

Flags

List and manage flags:

superflag flags list --app <name> --env <slug>
superflag flags create --app <name> --env <slug> --key <key> --type <type> --value <value>
superflag flags set --app <name> --env <slug> --key <key> --value <value>
superflag flags toggle --app <name> --env <slug> --key <key>
superflag flags delete --app <name> --env <slug> --key <key>

Idempotent upsert (uses context):

superflag flags upsert --key new-feature --type bool --value true
superflag flags upsert --key new-feature --type bool --value true --client  # Enable for client SDKs

Flag types: bool, string, number, json

Gradual rollout:

superflag flags rollout --key feature-x --percentage 25    # Roll out to 25%
superflag flags rollout --key feature-x --percentage 100   # Full rollout
superflag flags rollout --key feature-x --remove           # Remove rollout

A/B test variants:

# Format: --variant "value:weight:name"
superflag flags variants --key button-color \
  --variant "blue:50:control" \
  --variant "green:30:variant-a" \
  --variant "red:20:variant-b"

superflag flags variants --key button-color --remove  # Remove variants

Weights must sum to 100. Names are optional.

Bulk operations:

# From file
superflag flags bulk-set --file flags.json

# From stdin
echo '{"feature-a": true, "feature-b": "new-value"}' | superflag flags bulk-set

JSON format: {"flag-key": value, ...}

Keys

superflag keys list --app <name> --env <slug>
superflag keys create --app <name> --env <slug> --type <sdk|pub>
superflag keys revoke <key-id>

Key types:

• sdk - Server-side SDK key (full config access)
• pub - Client-side public key (filtered to client-enabled flags only)

Global Options

| Option | Description | |--------|-------------| | --json | Output as JSON | | --quiet, -q | Suppress non-essential output | | --app <name> | Override app context for this command | | --env <slug> | Override env context for this command | | --help, -h | Show help | | --version, -v | Show version |

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | SUPERFLAG_BASE_URL | https://superflag.sh | Base URL for API/auth endpoints (overridden by SUPERFLAG_API_URL / SUPERFLAG_AUTH_URL) | | SUPERFLAG_API_URL | https://superflag.sh/api/v1 | API endpoint | | SUPERFLAG_AUTH_URL | https://superflag.sh/cli-auth | Auth endpoint |

Exit Codes

| Code | Meaning | |------|---------| | 0 | Success | | 1 | Generic error | | 2 | Authentication or context required | | 3 | Resource not found |

Development

# Clone and install
git clone <repo>
cd superflag-cli
bun install

# Run in development
bun run dev <command>
bun run dev use myapp staging
bun run dev get feature-x

# Build
bun run build

# Type check
bun run typecheck

# Run tests
bun test

License

MIT