npm package: @superflag-sh/cli
Description: CLI for Superflag feature flags
Author: Superflag
Latest version: 0.1.6

# @superflag-sh/cli

[![npm version](https://img.shields.io/npm/v/@superflag-sh/cli.svg)](https://www.npmjs.com/package/@superflag-sh/cli)

Command-line interface for managing [Superflag](https://superflag.sh) feature flags and remote config.

## Quick Start

```bash
# 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:

```bash
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:

```bash
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:

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

Check your current context with:

```bash
superflag status
```

## Commands

### Quick Commands

These commands use your saved context for fast flag operations:

```bash
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

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

### Apps

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

### Environments

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

### Flags

**List and manage flags:**

```bash
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):**

```bash
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:**

```bash
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:**

```bash
# 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:**

```bash
# 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

```bash
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

```bash
# 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