@superflag-sh/cli 0.1.2 → 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,33 +1,49 @@
 {
-  "name": "@superflag-sh/cli",
-  "version": "0.1.2",
-  "description": "CLI for Superflag feature flags",
-  "type": "module",
-  "bin": {
-    "superflag": "./dist/index.js"
-  },
-  "files": [
-    "dist"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/superflag-sh/cli"
-  },
-  "keywords": [
-    "feature-flags",
-    "cli",
-    "superflag"
-  ],
-  "author": "Superflag",
-  "license": "MIT",
-  "devDependencies": {
-    "@types/bun": "^1.3.5",
-    "@types/node": "^22.0.0",
-    "typescript": "^5.0.0"
-  },
-  "scripts": {
-    "build": "rm -rf dist && bun build ./src/index.ts --outdir dist --target node --format esm && chmod +x dist/index.js",
-    "dev": "bun run src/index.ts",
-    "typecheck": "tsc --noEmit"
-  }
+	"name": "@superflag-sh/cli",
+	"version": "0.1.4",
+	"description": "CLI for Superflag feature flags",
+	"type": "module",
+	"bin": {
+		"superflag": "./dist/index.js"
+	},
+	"files": [
+		"dist"
+	],
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/superflag-sh/cli"
+	},
+	"keywords": [
+		"feature-flags",
+		"cli",
+		"superflag"
+	],
+	"author": "Superflag",
+	"license": "MIT",
+	"devDependencies": {
+		"@types/bun": "^1.3.5",
+		"@types/node": "^22.0.0",
+		"husky": "^9.1.7",
+		"lint-staged": "^16.2.7",
+		"typescript": "^5.0.0"
+	},
+	"scripts": {
+		"build": "rm -rf dist && bun build ./src/index.ts --outdir dist --target node --format esm && chmod +x dist/index.js",
+		"dev": "bun run src/index.ts",
+		"typecheck": "tsc --noEmit",
+		"test": "bun test",
+		"test:watch": "bun test --watch",
+		"prepare": "husky"
+	},
+	"dependencies": {
+		"@biomejs/biome": "^2.3.11"
+	},
+	"lint-staged": {
+		"*.{js,ts,cjs,mjs,d.cts,d.mts,jsx,tsx,json,jsonc}": [
+			"biome check --write --unsafe --staged --no-errors-on-unmatched"
+		],
+		"**/*.test.ts": [
+			"bun test"
+		]
+	}
 }