securenow 7.5.0 → 7.6.0

package/SKILL-CLI.md

@@ -9,22 +9,22 @@ Use the `securenow` CLI to perform security DevOps from the terminal: manage app
 npm install -g securenow
 
 # Or install per-project and use via npx
-npm install securenow
+npm install securenow@latest
 npx securenow <command>
 ```
 
-**Full parity with the SDK:** every capability the `securenow` Node SDK exposes has a CLI counterpart — redaction, CIDR matching, log/span emission, firewall preload, config inspection. If you can do it in code, you can do it from the terminal.
-
-**MCP parity (v7.5+):** the same package also ships a local stdio MCP server for Codex, Claude, and other MCP clients:
-
-```bash
-npx securenow login
-codex mcp add securenow -- npx securenow mcp
-# or
-npx -p securenow securenow-mcp
-```
-
-The MCP server reuses `.securenow/credentials.json` and exposes apps, traces, logs, firewall, IP intelligence, forensics, notifications, remediation tools, bundled docs resources, and setup prompts. Write tools require `confirm:true` plus a reason.
+**Full parity with the SDK:** every capability the `securenow` Node SDK exposes has a CLI counterpart — redaction, CIDR matching, log/span emission, firewall preload, config inspection. If you can do it in code, you can do it from the terminal.
+
+**MCP parity (v7.5+):** the same package also ships a local stdio MCP server for Codex, Claude, and other MCP clients:
+
+```bash
+npx securenow login
+codex mcp add securenow -- npx securenow mcp
+# or
+npx -p securenow securenow-mcp
+```
+
+The MCP server reuses `.securenow/credentials.json` and exposes apps, traces, logs, firewall, IP intelligence, forensics, notifications, remediation tools, bundled docs resources, and setup prompts. Write tools require `confirm:true` plus a reason.
 
 ### Authenticate
 
@@ -35,15 +35,17 @@ securenow login --token <JWT>   # headless / CI login (get token from dashboard
 securenow whoami            # verify session (shows email, app, auth source)
 ```
 
-**Zero-config flow (v7+):** the browser step lets the user pick (or create) an app. The CLI stores the app's **key (UUID)**, **name**, and **instance URL** in `.securenow/credentials.json`. The SDK reads this file at boot and sends traces/logs to the right app bucket — **no env vars required for local dev**.
-
-**Default-on security (v7.4+):** after picking or creating the app, `securenow login` turns on that app's firewall toggle, mints an API key with `firewall:read + blocklist:read + allowlist:read` scopes, and writes it into `.securenow/credentials.json`. Traces, logs, POST body capture, multipart metadata capture, and the firewall are enabled by default. No `SECURENOW_API_KEY` env var is needed. To add or rotate a key later without re-running login, use `securenow api-key set snk_live_...` (see [API Key Management](#api-key-management) below).
+**Zero-config flow (v7+):** the browser step lets the user pick (or create) an app. The CLI stores the app's **key (UUID)**, **name**, and **instance URL** in `.securenow/credentials.json`. The SDK reads this file at boot and sends traces/logs to the right app bucket — **no env vars required for local dev or production**.
 
-Credentials resolve in order: `SECURENOW_TOKEN` env var → project `.securenow/credentials.json` → global `~/.securenow/credentials.json`.
+**Default-on security (v7.5.1+):** after picking or creating the app, `securenow login` turns on that app's firewall toggle, mints an API key with `firewall:read + blocklist:read + allowlist:read` scopes, and writes it into `.securenow/credentials.json`. Traces, logs, POST body capture, multipart metadata capture, and the firewall are enabled by default. No `SECURENOW_API_KEY` env var is needed. To add or rotate a key later without re-running login, use `securenow api-key set snk_live_...` (see [API Key Management](#api-key-management) below).
 
-The **firewall API key** resolves in a slightly different order: `SECURENOW_API_KEY` env var (only if it starts with `snk_live_`) → project `.securenow/credentials.json` → global `~/.securenow/credentials.json`. An env var that isn't the `snk_live_` format is ignored, so the file can still win.
+Credentials resolve in order: project `.securenow/credentials.json` -> global `~/.securenow/credentials.json`. Legacy env vars are fallback-only for existing deployments.
 
-For CI / Docker / production, set env vars directly (always win over the file): `SECURENOW_APPID=<uuid>`, `SECURENOW_INSTANCE=<url>`, `SECURENOW_API_KEY=snk_live_<...>`.
+The **firewall API key** should live in the same credentials file as `apiKey`. Legacy `SECURENOW_API_KEY` overrides are honored only when they start with `snk_live_`.
+
+For CI / Docker / production, use `securenow credentials runtime --env production` to generate a tokenless runtime file, then mount/copy it as `.securenow/credentials.json`.
+
+**Environment model:** use one SecureNow app key for local, preview, staging, and production. The credentials field `config.runtime.deploymentEnvironment` separates traces/logs/firewall/forensics by environment. CLI security commands default to `production`; pass `--env local`, `--env staging`, or `--env all` only when that scope is intentional.
 
 ### Integrate With Your App
 
@@ -60,10 +62,11 @@ node -r securenow/register src/index.js
 For Next.js, run the interactive scaffolding:
 
 ```bash
-securenow init --key snk_live_...
+securenow login
+securenow init
 ```
 
-This auto-detects your framework and creates the necessary `instrumentation.ts`, `next.config.js` changes, and writes your API key to `.env.local`.
+This auto-detects your framework, creates the necessary `instrumentation.ts` and `next.config.js` changes, and reuses the app, instance, and firewall key written by login to `.securenow/credentials.json`.
 
 ### Install This Skill in Cursor
 
@@ -76,12 +79,12 @@ Config lives in `~/.securenow/` (global) and optionally `.securenow/` (per-proje
 | File | Content |
 |------|---------|
 | `~/.securenow/config.json` | `apiUrl`, `appUrl`, `defaultApp`, `output` |
-| `~/.securenow/credentials.json` | `token`, `email`, `expiresAt` (global) |
-| `.securenow/credentials.json` | `token`, `email`, `expiresAt` (project-local, use `login --local`) |
+| `~/.securenow/credentials.json` | `token`, `email`, `expiresAt`, `apiKey`, `app`, `config` (global, use `login --global`) |
+| `.securenow/credentials.json` | `token`, `email`, `expiresAt`, `apiKey`, `app`, `config`, `_securenow.explanations` (project-local default) |
 
-**Credential resolution order:** `SECURENOW_TOKEN` env var → `.securenow/credentials.json` (project) → `~/.securenow/credentials.json` (global).
+**Credential resolution order:** `.securenow/credentials.json` (project) -> `~/.securenow/credentials.json` (global). Legacy env vars are fallback-only for existing deployments.
 
-**Firewall API key resolution (v7.1+):** `SECURENOW_API_KEY` env var (only honored if it starts with `snk_live_`) → project `.securenow/credentials.json` → global `~/.securenow/credentials.json`. Use `securenow api-key set` to write the key to the credentials file without touching env vars.
+**Firewall API key resolution (v7.5.1+):** project `.securenow/credentials.json` -> global `~/.securenow/credentials.json`. Use `securenow login` for default setup or `securenow api-key set` to rotate a key without touching env vars.
 
 ```bash
 securenow config set apiUrl https://api.securenow.ai
@@ -91,7 +94,7 @@ securenow config get defaultApp          # show one
 securenow config path                    # print file paths + active auth source
 ```
 
-Environment overrides: `SECURENOW_TOKEN` (JWT), `SECURENOW_API_URL`, `SECURENOW_APP_URL`, `SECURENOW_APP` (default app key).
+Legacy CLI overrides still exist for existing automation (`SECURENOW_TOKEN`, `SECURENOW_API_URL`, `SECURENOW_APP_URL`, `SECURENOW_APP`), but file credentials are the default path.
 
 ## Global Flags
 
@@ -124,13 +127,13 @@ Spawns `node --require securenow/register [--import otel/hook.mjs] <script>`. ES
 ### Authentication
 
 ```bash
-securenow login                   # browser-based OAuth (stores in global ~/.securenow/)
-securenow login --token <JWT>     # headless / CI login
-securenow login --local           # save credentials to project .securenow/ (per-project session)
-securenow logout                  # clear active credentials (local if present, else global)
-securenow logout --local          # clear project-local credentials only
-securenow whoami                  # show email, user ID, API URL, auth source, expiry, default app
-```
+securenow login                   # browser-based OAuth (stores in project ./.securenow/)
+securenow login --token <JWT>     # headless / CI login
+securenow login --global          # save credentials to ~/.securenow/ instead
+securenow logout                  # clear active credentials (local if present, else global)
+securenow logout --global         # clear global credentials only
+securenow whoami                  # show email, user ID, API URL, auth source, expiry, default app
+```
 
 ### Applications
 
@@ -147,14 +150,15 @@ securenow apps scan [--yes]                  # scan all app domains for new subd
 
 ### API Key Management
 
-Manage the firewall API key stored in the credentials file. Since v7.1.0 the firewall reads `snk_live_...` keys from `.securenow/credentials.json` so no env var is required.
+Manage the firewall API key stored in the credentials file. Since v7.5.1 the login flow writes `snk_live_...` keys to `.securenow/credentials.json` by default, so no env var is required for local dev.
 
 ```bash
 securenow api-key set snk_live_xxxxxxxxxx    # save to project ./.securenow/ (default)
 securenow api-key set snk_live_xxx --global  # save to ~/.securenow/ instead
-securenow api-key show                       # print the masked current key + its source
-securenow api-key clear                      # remove just the API key (keeps session/app)
-securenow api-key clear --global             # same, but from the global file
+securenow api-key show                       # print the masked current key + its source
+securenow api-key clear                      # remove just the API key (keeps session/app)
+securenow api-key clear --global             # same, but from the global file
+securenow credentials runtime --env production # write .securenow/credentials.production.json for production secret-file deploys
 ```
 
 The key must start with `snk_live_`. `securenow login` with firewall enabled writes the key automatically; use `api-key set` when you already have a key from the dashboard, or to rotate it later.
@@ -162,19 +166,21 @@ The key must start with `snk_live_`. `securenow login` with firewall enabled wri
 ### Init — Project Setup
 
 ```bash
-securenow init [--key <API_KEY>]
+securenow init [--env local] [--key <API_KEY>]
 ```
 
-Auto-detects framework (Next.js, Nuxt, Express, Fastify, Koa, Hapi, Node) from `package.json`. Then:
-- **Next.js**: creates `instrumentation.ts/js`, suggests `withSecureNow()` in `next.config`
-- **Nuxt**: tells you to add `securenow/nuxt` to modules
-- **Node/Express/etc.**: suggests adding `-r securenow/register` to start script
-- Writes `SECURENOW_API_KEY` to `.env.local` or `.env` if `--key` provided
+Auto-detects framework (Next.js, Nuxt, Express, Fastify, Koa, Hapi, Node) from `package.json`. Then:
+- **Credentials**: ensures `.securenow/credentials.json` exists, has secure defaults/explanations, and `.securenow/` is gitignored
+- **Next.js**: creates `instrumentation.ts/js` with `securenow/nextjs` + `securenow/nextjs-auto-capture`, and adds `serverExternalPackages: ['securenow']` when the config can be patched safely
+- **Existing Next.js files**: prints a Codex/Claude-ready merge prompt when instrumentation or config already exists or is too custom to safely patch
+- **Nuxt**: tells you to add `securenow/nuxt` to modules
+- **Node/Express/etc.**: suggests adding `-r securenow/register` to start script
+- Reuses `.securenow/credentials.json` written by login; production should mount/copy the tokenless runtime file generated by `securenow credentials runtime --env production`
 
 ### Dashboard & Status
 
 ```bash
-securenow status [--app <key>]               # dashboard overview
+securenow status [--app <key>] [--env local|production|all] # dashboard overview
 securenow analytics [--app <key>]            # response analytics
 ```
 
@@ -183,18 +189,18 @@ securenow analytics [--app <key>]            # response analytics
 ### Traces
 
 ```bash
-securenow traces [--app <key>] [--limit N] [--start ISO] [--end ISO]
-securenow traces list --app my-app --limit 50
-securenow traces show <traceId>              # full trace detail with spans
-securenow traces analyze <traceId>           # AI-powered trace analysis
+securenow traces [--app <key>] [--env production] [--limit N] [--start ISO] [--end ISO]
+securenow traces list --app my-app --env production --limit 50
+securenow traces show <traceId> --env production      # full trace detail with spans
+securenow traces analyze <traceId> --env production   # AI-powered trace analysis
 ```
 
 ### Logs
 
 ```bash
-securenow logs [--app <key>] [--limit N] [--minutes M] [--level error|warn|info]
-securenow logs list --app my-app --minutes 30 --level error
-securenow logs trace <traceId>               # logs correlated to a specific trace
+securenow logs [--app <key>] [--env production] [--limit N] [--minutes M] [--level error|warn|info]
+securenow logs list --app my-app --env production --minutes 30 --level error
+securenow logs trace <traceId> --env production       # logs correlated to a specific trace
 ```
 
 ### Notifications
@@ -226,15 +232,15 @@ securenow alerts history [--limit N]         # past triggered alerts
 ```bash
 securenow ip <ip-address>                    # lookup (geo, ASN, threat score, reputation)
 securenow ip lookup <ip-address>             # same as above
-securenow ip traces <ip-address>             # traces originating from this IP
+securenow ip traces <ip-address> --env production # traces originating from this IP
 ```
 
 ### Forensics — Natural Language Security Queries
 
 ```bash
-securenow forensics "show me all SQL injection attempts in the last 24h"
-securenow forensics query "top 10 IPs by blocked requests" --app my-app
-securenow forensics chat --app my-app        # interactive forensics chat session
+securenow forensics "show me all SQL injection attempts in the last 24h" --env production
+securenow forensics query "top 10 IPs by blocked requests" --app my-app --env production
+securenow forensics chat --app my-app --env production # interactive forensics chat session
 securenow forensics library                  # view saved/template queries
 ```
 
@@ -252,11 +258,11 @@ securenow api-map stats                      # endpoint statistics
 
 ```bash
 securenow firewall                           # show status (default)
-securenow firewall status                    # layers, sync time, blocked count, API key info
+securenow firewall status --env production   # layers, sync time, blocked count, API key info
 securenow firewall test-ip <ip>              # check if IP would be blocked
 ```
 
-**Zero-config setup (v7.4+):** running `securenow login` enables the selected app's firewall toggle, auto-mints an API key (scoped `firewall:read + blocklist:read + allowlist:read`), and writes it to the credentials file after the app is selected. No `SECURENOW_API_KEY` env var needed. If the user already has a key, `securenow api-key set snk_live_...` achieves the same thing. See [the landing firewall page](https://securenow.ai/firewall) for an overview.
+**Zero-config setup (v7.5.1+):** running `securenow login` enables the selected app's firewall toggle, auto-mints an API key (scoped `firewall:read + blocklist:read + allowlist:read`), and writes it to the credentials file after the app is selected. No `SECURENOW_API_KEY` env var needed. If the user already has a key, `securenow api-key set snk_live_...` achieves the same thing. See [the landing firewall page](https://securenow.ai/firewall) for an overview.
 
 ### Blocklist — Block Malicious IPs
 
@@ -375,7 +381,7 @@ securenow test-span
 securenow test-span "ci.smoke-test"          # custom span name
 ```
 
-Both commands use the resolved `SECURENOW_INSTANCE` / `OTEL_EXPORTER_OTLP_*` endpoints. Honors `OTEL_EXPORTER_OTLP_HEADERS` for API-key auth. Returns non-zero on HTTP errors so CI/cron can detect failures.
+Both commands use the resolved collector settings from `.securenow/credentials.json` (`app.instance`, `config.otel.*`) and return non-zero on HTTP errors so CI/cron can detect failures.
 
 ### Utilities — Redaction, CIDR, Diagnostics
 
@@ -390,7 +396,7 @@ securenow redact @request.json --fields internal_id,sessionHash
 securenow cidr match 10.0.0.5 10.0.0.0/24,192.168.0.0/16
 securenow cidr parse 10.0.0.0/24             # network, broadcast, mask, size
 
-# Show resolved config (service name, endpoints, env vars, firewall layers)
+# Show resolved config (service name, endpoints, credentials, firewall layers)
 securenow env                                # human-readable
 securenow env --json                         # pipe to jq
 
@@ -448,7 +454,8 @@ securenow fp mark <notification-id> <ip> --rule-scope this_rule --reason "Known
 ```bash
 securenow apps create my-new-app --hosts api.example.com,app.example.com
 securenow apps default my-new-app
-securenow init --key snk_live_abc123...
+securenow login
+securenow init
 securenow run src/index.js
 securenow status --json
 ```
@@ -482,10 +489,10 @@ All commands support `--json` for structured output. When piping to other tools
 
 | Exit code / Error | Meaning | Recovery |
 |------------------|---------|----------|
-| `Session expired` | JWT expired | `securenow login` (or `login --local`) |
-| `Not logged in` | No token found | `securenow login` or set `SECURENOW_TOKEN` env var |
-| `Access denied (403)` | Insufficient plan or permissions | Upgrade plan or check user role |
-| `Cannot connect` | API unreachable | Check `SECURENOW_API_URL` or network |
+| `Session expired` | JWT expired | `securenow login` (or `login --global` for shared credentials) |
+| `Not logged in` | No token found | `securenow login` or mount/copy the right `.securenow/credentials.json` |
+| `Access denied (403)` | Insufficient plan or permissions | Upgrade plan or check user role |
+| `Cannot connect` | API unreachable | Check `securenow config get apiUrl` or network |
 | `Unknown command` | Typo or unrecognized command | `securenow help` |
 
 Set `SECURENOW_DEBUG=1` for full stack traces on any error.