> ## 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.

# Commands

> Complete reference for all Superflag CLI commands

# CLI Commands Reference

Complete reference for all available commands in the Superflag CLI.

<Info>
  Using Claude Code? Check out the [Claude Code skill](/cli/claude-code) for AI-powered flag management.
</Info>

## Quick Commands

Optimized for automation and AI agents with minimal output.

### use

Set default app and environment context.

```bash theme={null}
superflag use <app> <env>
```

**Example:**

```bash theme={null}
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.

```bash theme={null}
superflag get <key>
```

**Example:**

```bash theme={null}
superflag get dark-mode
# Output: true
```

Requires context to be set with `superflag use`.

### set

Set a flag value using saved context.

```bash theme={null}
superflag set <key> <value>
```

**Example:**

```bash theme={null}
superflag set dark-mode false
# Output: ✓
```

Requires context to be set with `superflag use`.

### config

Dump full config as JSON.

```bash theme={null}
superflag config
```

**Example:**

```bash theme={null}
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.

```bash theme={null}
superflag login
```

Opens browser for OAuth authentication.

### logout

Log out and clear credentials.

```bash theme={null}
superflag logout
```

### whoami

Show current user.

```bash theme={null}
superflag whoami
# Output: Logged in as: you@example.com
```

### status

Show authentication and context status.

```bash theme={null}
superflag status
# Output:
# Auth: Logged in as you@example.com
# Context: my-app/production
```

## App Management

### apps list

List all your apps.

```bash theme={null}
superflag apps list
```

### apps create

Create a new app.

```bash theme={null}
superflag apps create <name>
```

**Example:**

```bash theme={null}
superflag apps create my-new-app
```

## Environment Management

### envs list

List environments for an app.

```bash theme={null}
superflag envs list --app <name>
```

**Example:**

```bash theme={null}
superflag envs list --app my-app
```

## Flag Management

### flags list

List all flags in an environment.

```bash theme={null}
superflag flags list --app <app> --env <env>
```

**Example:**

```bash theme={null}
superflag flags list --app my-app --env production
```

### flags create

Create a new flag.

```bash theme={null}
superflag flags create --app <app> --env <env> --key <key> --type <type> --value <value>
```

**Types:** `bool`, `string`, `number`, `json`

**Example:**

```bash theme={null}
superflag flags create \
  --app my-app \
  --env production \
  --key new-feature \
  --type bool \
  --value true
```

### flags set

Set a flag value.

```bash theme={null}
superflag flags set --app <app> --env <env> --key <key> --value <value>
```

**Example:**

```bash theme={null}
superflag flags set \
  --app my-app \
  --env production \
  --key dark-mode \
  --value false
```

### flags toggle

Toggle a boolean flag.

```bash theme={null}
superflag flags toggle --app <app> --env <env> --key <key>
```

**Example:**

```bash theme={null}
superflag flags toggle \
  --app my-app \
  --env production \
  --key beta-features
```

### flags delete

Delete a flag.

```bash theme={null}
superflag flags delete --app <app> --env <env> --key <key>
```

**Example:**

```bash theme={null}
superflag flags delete \
  --app my-app \
  --env production \
  --key old-feature
```

### flags upsert

Create or update a flag (idempotent).

```bash theme={null}
superflag flags upsert --key <key> --type <type> --value <value>
```

**Example:**

```bash theme={null}
# 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.

```bash theme={null}
superflag flags bulk-set [--file <path>]
```

**JSON Format:**

```json theme={null}
{
  "dark-mode": true,
  "api-url": "https://api.example.com",
  "max-retries": 3
}
```

**Example:**

```bash theme={null}
superflag flags bulk-set --file flags.json
```

If `--file` is not provided, reads from stdin:

```bash theme={null}
echo '{"dark-mode": true}' | superflag flags bulk-set
```

### flags rollout

Configure gradual rollout percentage for a flag.

```bash theme={null}
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:**

```bash theme={null}
# 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.

```bash theme={null}
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:**

```bash theme={null}
# 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.

```bash theme={null}
superflag keys list --app <app> --env <env>
```

### keys create

Create a new API key.

```bash theme={null}
superflag keys create --app <app> --env <env> --type <type>
```

**Types:** `sdk`, `pub`

**Example:**

```bash theme={null}
superflag keys create \
  --app my-app \
  --env production \
  --type pub
```

### keys revoke

Revoke an API key.

```bash theme={null}
superflag keys revoke <key-id>
```

## Options

### Global Options

Available on all commands:

| Option            | Description  |
| ----------------- | ------------ |
| `--help`, `-h`    | Show help    |
| `--version`, `-v` | Show version |

## Exit Codes

| Code | Meaning           |
| ---- | ----------------- |
| `0`  | Success           |
| `1`  | Error             |
| `2`  | Not authenticated |
| `3`  | Not found         |

## Examples

### Set up a new project

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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

<CardGroup cols={2}>
  <Card title="CI/CD Usage" icon="robot" href="/cli/ci-cd">
    Use the CLI in automation
  </Card>

  <Card title="Installation" icon="download" href="/cli/installation">
    Install and update the CLI
  </Card>
</CardGroup>