securenow 5.3.1 → 5.3.3

package/NPM_README.md

@@ -16,6 +16,7 @@ OpenTelemetry instrumentation library for Node.js applications. Send distributed
 
 - [Installation](#installation)
 - [Quick Start](#quick-start)
+- [CLI — Command Line Interface](#cli--command-line-interface)
 - [Framework-Specific Setup](#framework-specific-setup)
   - [Express.js](#expressjs)
   - [Next.js](#nextjs)
@@ -96,6 +97,286 @@ You'll see confirmation in the console:
 
 ---
 
+## CLI — Command Line Interface
+
+The `securenow` CLI gives you full access to the SecureNow platform from the terminal — no browser required for day-to-day workflows. Zero additional dependencies.
+
+### Getting Started
+
+```bash
+# Log in (opens browser for OAuth)
+npx securenow login
+
+# Or use a token for CI/headless environments
+npx securenow login --token <YOUR_JWT>
+
+# Check who you're logged in as
+npx securenow whoami
+```
+
+### Managing Applications
+
+```bash
+# List all applications
+npx securenow apps
+
+# Create a new application
+npx securenow apps create my-production-app --hosts api.example.com,app.example.com
+
+# Get application details (including the app key)
+npx securenow apps info <app-id>
+
+# Set a default app so you don't need --app on every command
+npx securenow apps default <app-key>
+
+# Delete an application
+npx securenow apps delete <app-id> --force
+```
+
+### Viewing Traces
+
+```bash
+# List recent traces (uses default app, or specify --app)
+npx securenow traces
+npx securenow traces --app <key> --limit 50
+
+# Show detailed spans for a trace
+npx securenow traces show <traceId>
+
+# AI-powered security analysis of a trace
+npx securenow traces analyze <traceId>
+```
+
+### Viewing Logs
+
+```bash
+# List recent logs
+npx securenow logs
+npx securenow logs --app <key> --minutes 30 --level error
+
+# Show logs for a specific trace
+npx securenow logs trace <traceId>
+```
+
+### Security Issues
+
+```bash
+# List all issues
+npx securenow issues
+npx securenow issues --status open
+
+# Show issue details with AI analysis
+npx securenow issues show <issue-id>
+
+# Resolve an issue
+npx securenow issues resolve <issue-id>
+```
+
+### Notifications
+
+```bash
+# List notifications
+npx securenow notifications
+
+# Check unread count
+npx securenow notifications unread
+
+# Mark as read
+npx securenow notifications read <id>
+npx securenow notifications read-all
+```
+
+### Alerting
+
+```bash
+# View alert rules, channels, and history
+npx securenow alerts rules
+npx securenow alerts channels
+npx securenow alerts history --limit 20
+```
+
+### IP Intelligence & Blocklist
+
+```bash
+# Look up any IP — geo, abuse score, verdict, risk factors
+npx securenow ip 203.0.113.42
+
+# Show traces from a specific IP
+npx securenow ip traces 203.0.113.42
+
+# Manage the blocklist
+npx securenow blocklist
+npx securenow blocklist add 203.0.113.42 --reason "Brute force scanner"
+npx securenow blocklist remove <id>
+npx securenow blocklist stats
+
+# Manage trusted IPs
+npx securenow trusted
+npx securenow trusted add 10.0.0.1 --label "Office VPN"
+npx securenow trusted remove <id>
+```
+
+### Forensic Queries
+
+Ask questions in plain English — the AI translates them to SQL and runs them against your data.
+
+```bash
+# Run a forensic query
+npx securenow forensics "show top 10 attacking IPs in the last hour"
+npx securenow forensics "which endpoints had 5xx errors today"
+
+# Browse the saved query library
+npx securenow forensics library
+```
+
+### API Map
+
+```bash
+# View all discovered API endpoints
+npx securenow api-map
+
+# API map statistics
+npx securenow api-map stats
+```
+
+### Analytics & Dashboard
+
+```bash
+# Response code analytics
+npx securenow analytics --app <key>
+
+# Full dashboard overview (apps, protection status, unread alerts)
+npx securenow status
+```
+
+### Instances
+
+```bash
+# List ClickHouse instances
+npx securenow instances
+
+# Test an instance connection
+npx securenow instances test <id>
+```
+
+### Configuration
+
+```bash
+# View all config
+npx securenow config get
+
+# Set values
+npx securenow config set apiUrl https://custom-api.example.com
+npx securenow config set defaultApp <app-key>
+npx securenow config set format json
+
+# Show config file paths
+npx securenow config path
+```
+
+Config files are stored in `~/.securenow/`:
+
+| File | Description |
+|------|-------------|
+| `config.json` | API URL, default app, output format |
+| `credentials.json` | Auth token (file permissions: 0600) |
+
+### Initialize Instrumentation
+
+```bash
+# Interactive setup — creates instrumentation files for Next.js
+npx securenow init
+npx securenow init --ts --src --force
+```
+
+### Global Flags
+
+Every command supports these flags:
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--json` | `-j` | Output as JSON for scripting and CI/CD |
+| `--help` | | Show help for the command |
+| `--app <key>` | | Override the default application key |
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `SECURENOW_API_URL` | Override the API base URL |
+| `SECURENOW_DEBUG` | Show stack traces on errors |
+| `NO_COLOR` | Disable colored output |
+
+### CI/CD Integration
+
+```bash
+# Authenticate with a token in CI
+npx securenow login --token $SECURENOW_TOKEN
+
+# Use --json for machine-readable output
+npx securenow issues --json | jq '.[] | select(.severity == "critical")'
+
+# Check for critical issues in a pipeline
+ISSUES=$(npx securenow issues --json --status open)
+CRITICAL=$(echo "$ISSUES" | jq '[.[] | select(.severity == "critical")] | length')
+if [ "$CRITICAL" -gt "0" ]; then
+  echo "Found $CRITICAL critical issues!"
+  exit 1
+fi
+```
+
+### Complete Command Reference
+
+| Category | Command | Description |
+|----------|---------|-------------|
+| **Auth** | `login` | Authenticate via browser or `--token` |
+| | `logout` | Clear credentials |
+| | `whoami` | Show session info |
+| **Apps** | `apps` | List applications |
+| | `apps create <name>` | Create application |
+| | `apps info <id>` | Application details |
+| | `apps delete <id>` | Delete application |
+| | `apps default <key>` | Set default app |
+| **Observe** | `traces` | List traces |
+| | `traces show <id>` | Trace details |
+| | `traces analyze <id>` | AI trace analysis |
+| | `logs` | List logs |
+| | `logs trace <id>` | Logs for a trace |
+| | `analytics` | Response analytics |
+| | `status` | Dashboard overview |
+| **Detect** | `issues` | List issues |
+| | `issues show <id>` | Issue details |
+| | `issues resolve <id>` | Resolve issue |
+| | `notifications` | List notifications |
+| | `notifications unread` | Unread count |
+| | `notifications read <id>` | Mark read |
+| | `notifications read-all` | Mark all read |
+| | `alerts rules` | Alert rules |
+| | `alerts channels` | Alert channels |
+| | `alerts history` | Alert history |
+| **Investigate** | `ip <addr>` | IP intelligence |
+| | `ip traces <addr>` | Traces from IP |
+| | `forensics "<query>"` | NL forensic query |
+| | `forensics library` | Saved queries |
+| | `api-map` | API endpoints |
+| | `api-map stats` | API stats |
+| **Remediate** | `blocklist` | Blocked IPs |
+| | `blocklist add <ip>` | Block IP |
+| | `blocklist remove <id>` | Unblock IP |
+| | `blocklist stats` | Block stats |
+| | `trusted` | Trusted IPs |
+| | `trusted add <ip>` | Add trusted IP |
+| | `trusted remove <id>` | Remove trusted |
+| **Settings** | `instances` | List instances |
+| | `instances test <id>` | Test connection |
+| | `config get` | Show config |
+| | `config set <k> <v>` | Set config value |
+| | `config path` | Config file paths |
+| | `init` | Setup instrumentation |
+| | `version` | Show version |
+
+---
+
 ## Framework-Specific Setup
 
 ### Express.js

package/README.md

@@ -36,7 +36,37 @@ SECURENOW_INSTANCE=http://your-otlp-collector:4318
 npx securenow init
 ```
 
-**Done!** 🎉 See [Next.js Complete Guide](./docs/NEXTJS-GUIDE.md) for details.
+**Done!** See [Next.js Complete Guide](./docs/NEXTJS-GUIDE.md) for details.
+
+---
+
+### CLI — Manage Everything from the Terminal
+
+```bash
+# Authenticate
+npx securenow login
+
+# Create an app and get the key
+npx securenow apps create my-app
+
+# Set it as default so you don't need --app every time
+npx securenow config set defaultApp <key>
+
+# View traces, logs, issues
+npx securenow traces
+npx securenow logs
+npx securenow issues
+
+# IP intelligence, forensic queries, blocklist
+npx securenow ip 1.2.3.4
+npx securenow forensics "show top attacking IPs in the last hour"
+npx securenow blocklist add 1.2.3.4 --reason "scanner"
+
+# Full dashboard overview
+npx securenow status
+```
+
+Run `npx securenow help` for all commands. See the [CLI Reference](#cli-reference) below.
 
 ---
 
@@ -173,7 +203,113 @@ SecureNow automatically instruments:
 
 ---
 
-## 🆘 Support
+## CLI Reference
+
+After installing the package, the `securenow` CLI is available via `npx securenow` or globally after `npm install -g securenow`.
+
+### Authentication
+
+| Command | Description |
+|---------|-------------|
+| `securenow login` | Log in via browser (opens OAuth flow) |
+| `securenow login --token <TOKEN>` | Log in with a token (for CI/headless) |
+| `securenow logout` | Clear stored credentials |
+| `securenow whoami` | Show current session info |
+
+### Applications
+
+| Command | Description |
+|---------|-------------|
+| `securenow apps` | List all applications |
+| `securenow apps create <name>` | Create app and get the app key |
+| `securenow apps info <id>` | Show application details |
+| `securenow apps delete <id>` | Delete an application |
+| `securenow apps default <key>` | Set default app for all commands |
+
+### Observability
+
+| Command | Description |
+|---------|-------------|
+| `securenow traces --app <key>` | List recent traces |
+| `securenow traces show <traceId>` | Show trace spans |
+| `securenow traces analyze <traceId>` | AI security analysis of a trace |
+| `securenow logs --app <key>` | View logs (with `--minutes`, `--level`) |
+| `securenow logs trace <traceId>` | View logs for a specific trace |
+| `securenow analytics` | Response code analytics overview |
+| `securenow status` | Full dashboard summary |
+
+### Detect & Respond
+
+| Command | Description |
+|---------|-------------|
+| `securenow issues` | List security issues |
+| `securenow issues show <id>` | Show issue details and AI analysis |
+| `securenow issues resolve <id>` | Mark an issue as resolved |
+| `securenow notifications` | List notifications |
+| `securenow notifications unread` | Show unread count |
+| `securenow notifications read <id>` | Mark notification as read |
+| `securenow notifications read-all` | Mark all as read |
+| `securenow alerts rules` | List alert rules |
+| `securenow alerts channels` | List alert channels |
+| `securenow alerts history` | View alert history |
+
+### Investigate
+
+| Command | Description |
+|---------|-------------|
+| `securenow ip <address>` | IP intelligence lookup (geo, abuse score, verdict) |
+| `securenow ip traces <address>` | Show traces originating from an IP |
+| `securenow forensics "<query>"` | Natural language forensic query (NL to SQL) |
+| `securenow forensics library` | View saved query library |
+| `securenow api-map` | View discovered API endpoints |
+| `securenow api-map stats` | API map statistics |
+
+### Remediation
+
+| Command | Description |
+|---------|-------------|
+| `securenow blocklist` | List blocked IPs |
+| `securenow blocklist add <ip>` | Block an IP (`--reason <reason>`) |
+| `securenow blocklist remove <id>` | Remove from blocklist |
+| `securenow blocklist stats` | Blocklist statistics |
+| `securenow trusted` | List trusted IPs |
+| `securenow trusted add <ip>` | Add trusted IP (`--label <label>`) |
+| `securenow trusted remove <id>` | Remove trusted IP |
+
+### Settings
+
+| Command | Description |
+|---------|-------------|
+| `securenow instances` | List ClickHouse instances |
+| `securenow instances test <id>` | Test instance connection |
+| `securenow config get` | Show all config values |
+| `securenow config set <key> <value>` | Set a config value |
+| `securenow config path` | Show config file locations |
+| `securenow init` | Initialize instrumentation files |
+| `securenow version` | Show CLI version |
+
+### Global Flags
+
+| Flag | Description |
+|------|-------------|
+| `--json` | Output as JSON (works on every command) |
+| `--help` | Show help for any command |
+| `--app <key>` | Specify app key (or set default with `config set defaultApp`) |
+
+### Configuration
+
+Credentials and settings are stored in `~/.securenow/`:
+
+| File | Purpose |
+|------|---------|
+| `~/.securenow/config.json` | API URL, default app, preferences |
+| `~/.securenow/credentials.json` | Auth token (restricted permissions) |
+
+Override the API URL with `securenow config set apiUrl <url>` or the `SECURENOW_API_URL` environment variable.
+
+---
+
+## Support
 
 - **Website:** [securenow.ai](http://securenow.ai/)
 - **Issues:** Report bugs and request features
@@ -181,6 +317,6 @@ SecureNow automatically instruments:
 
 ---
 
-## 📄 License
+## License
 
 ISC

package/cli/apps.js

@@ -56,8 +56,11 @@ async function create(args, flags) {
   if (flags.hosts) {
     body.hosts = flags.hosts.split(',').map(h => h.trim());
   }
+
   if (flags.instance) {
     body.instanceId = flags.instance;
+  } else if (process.stdin.isTTY) {
+    body.instanceId = await pickInstance();
   }
 
   const s = ui.spinner(`Creating application "${name}"`);
@@ -91,6 +94,61 @@ async function create(args, flags) {
   }
 }
 
+async function pickInstance() {
+  const s = ui.spinner('Loading instances');
+  let instances = [];
+  try {
+    const data = await api.get('/instances');
+    instances = data.instances || [];
+    s.stop('Instances loaded');
+  } catch {
+    s.stop('Could not load instances');
+    return null;
+  }
+
+  const FREE_TRIAL_LABEL = `${ui.c.green('Free Trial')} ${ui.c.dim('— SecureNow managed instance (no setup needed)')}`;
+
+  const choices = [{ label: FREE_TRIAL_LABEL, value: null }];
+
+  for (const inst of instances) {
+    const status = inst.status === 'active' ? ui.c.green('●') : ui.c.red('●');
+    const apps = inst.linkedApps ? ui.c.dim(` (${inst.linkedApps} app${inst.linkedApps !== 1 ? 's' : ''})`) : '';
+    choices.push({
+      label: `${status} ${inst.name}${apps} ${ui.c.dim(`[${inst._id}]`)}`,
+      value: inst._id,
+    });
+  }
+
+  const appUrl = config.getAppUrl();
+  choices.push({
+    label: `${ui.c.cyan('+')} Create a new instance ${ui.c.dim('(opens browser)')}`,
+    value: '__new__',
+  });
+
+  const selected = await ui.select('Which instance should this app use?', choices);
+
+  if (selected === '__new__') {
+    const url = `${appUrl}/dashboard/settings/instances`;
+    ui.info(`Opening ${ui.c.underline(url)}`);
+    openBrowser(url);
+    ui.info('Create your instance in the browser, then run this command again.');
+    process.exit(0);
+  }
+
+  return selected;
+}
+
+function openBrowser(url) {
+  const { execSync } = require('child_process');
+  try {
+    if (process.platform === 'darwin') execSync(`open "${url}"`);
+    else if (process.platform === 'win32') execSync(`start "" "${url}"`);
+    else execSync(`xdg-open "${url}"`);
+  } catch {
+    ui.warn(`Could not open browser. Visit: ${url}`);
+  }
+}
+
 async function info(args, flags) {
   requireAuth();
 

package/cli.js

@@ -60,7 +60,7 @@ const COMMANDS = {
     usage: 'securenow apps <subcommand> [options]',
     sub: {
       list: { desc: 'List all applications', run: (a, f) => require('./cli/apps').list(a, f) },
-      create: { desc: 'Create a new application', usage: 'securenow apps create <name> [--hosts host1,host2] [--instance <id>]', run: (a, f) => require('./cli/apps').create(a, f) },
+      create: { desc: 'Create a new application (interactive instance picker)', usage: 'securenow apps create <name> [--hosts host1,host2] [--instance <id>]', run: (a, f) => require('./cli/apps').create(a, f) },
       info: { desc: 'Show application details', usage: 'securenow apps info <id>', run: (a, f) => require('./cli/apps').info(a, f) },
       delete: { desc: 'Delete an application', usage: 'securenow apps delete <id> [--force]', run: (a, f) => require('./cli/apps').remove(a, f) },
       default: { desc: 'Set default application', usage: 'securenow apps default <key>', run: (a, f) => require('./cli/apps').setDefault(a, f) },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "securenow",
-  "version": "5.3.1",
+  "version": "5.3.3",
   "description": "OpenTelemetry instrumentation for Node.js and Next.js - Send traces and logs to any OTLP-compatible backend",
   "type": "commonjs",
   "main": "register.js",