@superflag-sh/cli 0.1.3 → 0.1.4

package/README.md

@@ -0,0 +1,212 @@
+# @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_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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@superflag-sh/cli",
-	"version": "0.1.3",
+	"version": "0.1.4",
 	"description": "CLI for Superflag feature flags",
 	"type": "module",
 	"bin": {