fuzzi-cli 0.1.0 → 0.1.1

package/README.md

@@ -1,92 +1,121 @@
 # Fuzzi CLI
 
-Node.js/TypeScript command-line tool for running Fuzzi security scans without a browser. Supports an interactive shell (`fuzzi`) and direct commands for CI/CD (`fuzzi scan <url>`).
-
-## Install
+Run Fuzzi security scans from your terminal. Interactive shell for daily use, scriptable commands for CI.
 
 ```bash
 npm install -g fuzzi-cli
-# or zero-install
-npx fuzzi-cli@latest scan https://example.com
+fuzzi
 ```
 
-## Quick start
+---
 
-1. Generate an API key at [app.fuzzi.dev/settings/api-keys](https://app.fuzzi.dev/settings/api-keys)
-2. Log in:
+## First run (30 seconds)
 
-```bash
-fuzzi auth login
+1. **Install** the CLI (above)
+2. **Run** `fuzzi`
+3. You'll see **Sign in to continue** — press **Enter**
+4. Your **browser opens** to app.fuzzi.dev — log in or sign up
+5. After authorizing, return to the terminal — you're in
+
+```
+› /scan example.com        # scan a site (https:// added automatically)
+› /scans                   # browse past scans
+› /help                    # all commands
+› /palette                 # search commands
 ```
 
-3. Run a scan:
+No browser? Use **`/auth-key`** to paste an API key from [Settings → API Keys](https://app.fuzzi.dev/settings/api-keys).
 
-```bash
-fuzzi scan https://example.com
-```
+---
 
-## Two modes
+## Two ways to use it
 
-| Invocation | Behavior |
-|------------|----------|
-| `fuzzi` | Interactive home screen + `>` slash-command REPL |
-| `fuzzi scan <url>` | One-shot command, exits (CI/scripting) |
+| You want… | Do this |
+|-----------|---------|
+| Explore scans interactively | `fuzzi` (opens the shell) |
+| One command in CI / a script | `fuzzi scan <url> --fail-on critical` |
 
-### Interactive slash commands
+---
 
-```
-/scan <url>       Run scan with live progress
-/scans            Browse recent scans
-/status           Auth status & rate limits
-/keys             View/revoke API keys
-/config k=v       Set local config
-/changelog        Release notes
-/help             All commands
-/exit             Leave the shell
-```
+## Interactive shell
 
-### Direct commands
+Slash commands (type at the `›` prompt):
 
-```bash
-fuzzi scan <url> [--title] [--env production|staging|development] [--wait] [--no-wait] [--format table|json|markdown] [--fail-on low|medium|high|critical] [--fail-threshold 0.0-1.0]
-fuzzi scans list [--status] [--risk-level] [--limit 20] [--format table|json]
-fuzzi scans get <scan-id> [--format table|json|markdown]
-fuzzi report <scan-id> --format pdf|csv|json [--output ./path]
-fuzzi whatif <scan-id> --set dimension=value [--format json]
-fuzzi compare <scan-a> <scan-b> [--format table|json]
-fuzzi auth login [--api-key] | logout | status
-fuzzi config get [key] | set <key> <value> | list
-fuzzi --version
-fuzzi --help
-```
+| Command | What it does |
+|---------|----------------|
+| `/scan <url>` | Run a scan, show live progress |
+| `/scans` | Browse recent scans |
+| `/status` | Account, API key expiry, rate limits |
+| `/keys` | List / revoke / create API keys |
+| `/auth` | Sign in via browser again |
+| `/auth-key` | Paste an API key manually |
+| `/config key=value` | Set CLI defaults |
+| `/palette` | Fuzzy-search all commands |
+| `/help` | Command reference |
+| `/exit` | Quit |
 
-## CI exit codes
+**Tips**
 
-| Code | Meaning |
-|------|---------|
-| 0 | Success; scan risk below `--fail-on` threshold |
-| 1 | Scan succeeded but risk meets/exceeds `--fail-on` |
-| 2 | Command failed (network, auth, invalid URL, etc.) |
+- **Tab** completes command names
+- Bare domains work: `/scan netflix.com` → `https://netflix.com`
+- `auth login` and `fuzzi auth login` are rewritten to `/auth` in the shell
+
+---
+
+## Scriptable commands (CI & automation)
 
 ```bash
-fuzzi scan https://staging.example.com --fail-on critical
-# exit 0 = risk < CRITICAL
-# exit 1 = risk >= CRITICAL (intentional gate)
-# exit 2 = scan error
-```
+# Scan and wait for result (default)
+fuzzi scan https://staging.example.com
 
-## Configuration
+# Fail CI if risk is HIGH or above
+fuzzi scan https://staging.example.com --fail-on high
 
-**Credentials:** `~/.fuzzi/credentials` (mode 600)
+# JSON for pipelines
+fuzzi scan https://example.com --format json
+
+# Machine-readable exit codes
+#   0 = success, risk below threshold
+#   1 = scan done, risk at/above --fail-on
+#   2 = error (network, auth, bad URL)
+```
 
-**CLI config:** `~/.fuzzi/config`
+### All commands
 
 ```bash
-fuzzi config set default_env staging
-fuzzi config set default_format markdown
+fuzzi auth login              # browser sign-in (default)
+fuzzi auth login --api-key    # paste key non-interactively
+fuzzi auth status
+fuzzi auth logout
+
+fuzzi scan <url> [--wait] [--no-wait] [--format table|json|markdown]
+               [--env production|staging|development]
+               [--fail-on low|medium|high|critical]
+               [--fail-threshold 0.0-1.0]
+
+fuzzi scans list [--status] [--risk-level] [--limit 20]
+fuzzi scans get <scan-id> [--format table|json|markdown]
+fuzzi report <scan-id> --format pdf|csv|json [-o file]
+fuzzi whatif <scan-id> --set dimension=0.5
+fuzzi compare <scan-a> <scan-b>
+
+fuzzi config list | get [key] | set <key> <value>
+fuzzi status
+fuzzi --help
 ```
 
-**Project config:** `.fuzzirc` (JSON) or `fuzzi.toml` in the working directory:
+---
+
+## Configuration
+
+| File | Purpose |
+|------|---------|
+| `~/.fuzzi/credentials` | API key (mode 600) |
+| `~/.fuzzi/config` | CLI defaults (`default_env`, `default_format`) |
+| `~/.fuzzi/history` | Shell command history |
+| `.fuzzirc` or `fuzzi.toml` | Project defaults in repo root |
+
+**Example `.fuzzirc`:**
 
 ```json
 {
@@ -95,29 +124,71 @@ fuzzi config set default_format markdown
     "environment": "staging",
     "fail_on": "high"
   },
-  "output": {
-    "format": "markdown"
-  }
+  "output": { "format": "markdown" }
 }
 ```
 
-CLI flags override project config values.
+Flags on the command line override file values.
+
+```bash
+fuzzi config set default_env staging
+fuzzi config set default_format markdown
+export FUZZI_API_URL=https://app.fuzzi.dev/api   # override API
+export FUZZI_DEBUG=1                              # debug logging
+```
+
+---
+
+## CI example (GitHub Actions)
+
+```yaml
+- name: Fuzzi security gate
+  run: |
+    npm install -g fuzzi-cli
+    fuzzi auth login --api-key "${{ secrets.FUZZI_API_KEY }}"
+    fuzzi scan https://staging.example.com --fail-on critical --format markdown
+```
+
+---
+
+## For web / frontend developers
+
+The CLI browser login flow requires pages and API routes on **app.fuzzi.dev**.
+
+See **[docs/frontend-integration.md](./docs/frontend-integration.md)** for:
+
+- `/cli-auth` page spec
+- `POST /api/cli/handoff` contract
+- API keys settings UI
+- Full feature parity checklist
+
+---
 
 ## Development
 
 ```bash
+git clone <repo>
+cd fuzzi-cli
 npm install
-npm run build
 npm test
-npm link   # optional global `fuzzi` command
+npm run build
+npm link          # optional: global `fuzzi` command
 ```
 
-## Brand
+---
 
-- Accent: `#4FC3A1` (teal)
-- Risk colors: LOW green, MEDIUM amber, HIGH red, CRITICAL purple
+## Publish to npm
 
-## v2 (not yet)
+```bash
+npm login
+npm publish --access public
+```
+
+Or tag `v0.1.0` and let GitHub Actions publish (requires `NPM_TOKEN` secret).
+
+---
 
-- Browser login (`fuzzi auth login --browser`)
-- GitHub Action wrapper
+## Brand
+
+- Accent: `#4FC3A1` (teal)
+- Risk: LOW green · MEDIUM amber · HIGH red · CRITICAL purple

package/assets/changelog.json

@@ -1,4 +1,14 @@
 [
+  {
+    "version": "0.1.1",
+    "date": "2026-06-19",
+    "highlights": [
+      "Browser sign-in on startup — press Enter to open app.fuzzi.dev",
+      "Full-width terminal UI and command palette",
+      "/auth-key fallback for API key paste",
+      "Frontend integration docs for web team"
+    ]
+  },
   {
     "version": "0.1.0",
     "date": "2026-06-19",