subto 9.0.2 → 9.0.3

package/README.md

@@ -1,43 +1,278 @@
 # Subto CLI
 
-Install:
+`subto` is the command-line client for Subto.One. It can:
 
-```
+- store your Subto API key locally
+- request and poll remote website scans
+- show your current account summary
+- start a local interactive assistant for scan results
+- upload sampled project files to the server for scanning
+- run local AI analysis on a project without uploading it
+- store a local OpenRouter key for local AI analysis
+- push an AI key to a running server's internal endpoint
+- fetch video diagnostics for a scan
+
+## Install
+
+```bash
 npm install -g subto
 ```
 
-Usage:
+## Quick start
+
+```bash
+subto login
+subto account
+subto scan https://example.com
+subto scan https://example.com --wait
+subto chat
+```
+
+## Global options
+
+```text
+-V, --version
+-v, --verbose
+--debug
+--chat
+--no-auto-skip
+--skip-prompt-ms <n>
+--skip-countdown-ms <n>
+--skip-force-ms <n>
+```
+
+- `--verbose` prints extra HTTP logging.
+- `--debug` prints request and response debugging details.
+- `--chat` starts the interactive assistant without requiring a subcommand.
+- `--no-auto-skip` and the `--skip-*` flags control the external-API auto-skip behavior used while polling scans.
+
+## Commands
+
+### `subto login`
+
+Stores your Subto API key in `~/.subto/config.json`.
+
+```bash
+subto login
+```
+
+### `subto account`
+
+Shows your current account summary.
+
+```bash
+subto account
+subto account --json
+```
+
+Output includes:
+
+- account name
+- email
+- account id
+- API call count
+- scan count
+- member-since date
+
+### `subto scan <url>`
 
+Requests a remote scan for a URL via the Subto API.
+
+```bash
+subto scan https://example.com
+subto scan https://example.com --wait
+subto scan https://example.com --no-wait
+subto scan https://example.com --json
+subto scan https://example.com --chat
 ```
-subto login      # store API key
-subto scan <url> # request a scan
+
+Options:
+
+- `--json` prints the raw JSON response.
+- `--wait` polls until the scan finishes and prints progress.
+- `--no-wait` returns immediately instead of polling.
+- `--chat` opens the local interactive assistant after the scan completes.
+
+If the server returns HTML instead of JSON, the CLI attempts to recover the `scanId` automatically. If it cannot, it saves the HTML response to a temporary file for inspection.
+
+### `subto scan upload [dir]`
+
+Uploads sampled files from a directory to the server and starts a scan.
+
+```bash
+subto scan upload
+subto scan upload .
+subto scan upload ./my-project --wait
 ```
 
-This package is a production CLI; it intentionally omits development instructions.
+Options:
 
-Advanced features
------------------
+- `--wait` polls until the remote analysis completes.
 
-- `subto upload [dir]` — upload your project directory to the built-in AI analyzer. The command samples files from the target directory, respecting a `.subtoignore` file (one pattern per line, `#` for comments). For safety the uploader always ignores `.env` files. The uploader limits total files and bytes to avoid extremely large uploads; see CLI flags `--max-files` and `--max-bytes`.
+Behavior:
 
-- `subto scan upload [dir]` — upload a directory to the server and request a scan. This command respects `.subtoignore` and always ignores `.env`. It uploads sampled file snippets (small files fully, larger files head only) and returns an `uploadId` and `scanId` you can use with the AI chat or to fetch scan status.
+- respects `.subtoignore`
+- always ignores `.env`
+- uploads sampled snippets rather than full large files
+- returns an `uploadId` and `scanId`
 
-- `subto upload [dir]` — run a local-only AI analysis on the sampled files (does not send files to the server). Useful when you want quick on-device feedback without uploading.
+### `subto chat [scanId]`
 
-`.subtoignore` format
-- One pattern per line.
-- Lines starting with `#` are comments.
-- Patterns may be folder names (e.g. `node_modules`), file globs/partials (e.g. `*.lock`), or specific files (`secret.txt`). The uploader uses simple matching: exact token, prefix, contains `/token`, or endsWith token. Examples:
+Starts the local interactive assistant for a scan.
 
+```bash
+subto chat
+subto chat <scanId>
+subto --chat
 ```
+
+If you do not provide a `scanId`, the CLI prompts for either:
+
+- a scan id
+- a path to a JSON file containing saved scan data
+
+The assistant can answer simple questions locally, and it will use a configured AI provider when one is available.
+
+### `subto upload [dir]`
+
+Runs local AI analysis on sampled project files without uploading them to the Subto server.
+
+```bash
+subto upload
+subto upload .
+subto upload ./project --max-files 300 --max-bytes 5242880
+```
+
+Options:
+
+- `--max-files <n>` limits the number of files included.
+- `--max-bytes <n>` limits the total bytes included.
+
+Behavior:
+
+- respects `.subtoignore`
+- always ignores `.env`
+- samples small files fully and large files partially
+- sends only the generated prompt and file snippets to the configured AI provider
+
+### `subto upload key [key]`
+
+Stores a local OpenRouter API key and model in `~/.subto/config.json` for local AI analysis.
+
+```bash
+subto upload key
+subto upload key <openrouter-api-key>
+```
+
+If no key is provided, the CLI prompts for one interactively, then prompts for a model.
+
+### `subto server-set-ai-key [key]`
+
+Pushes an AI provider key to a running server using the internal `/internal/set-ai-key` endpoint.
+
+```bash
+subto server-set-ai-key <key> --secret <internal-secret>
+subto server-set-ai-key --server https://subto.one --secret <internal-secret>
+subto server-set-ai-key --provider openai --model gpt-4o-mini --secret <internal-secret>
+```
+
+Options:
+
+- `--server <url>` overrides the server host base.
+- `--secret <secret>` sends the internal task secret header.
+- `--provider <provider>` chooses `openrouter` or `openai`.
+- `--model <model>` sets the requested model id.
+
+If you omit the key argument, the CLI tries to use a locally stored key.
+
+### `subto diag video <scanId>`
+
+Fetches server-side video diagnostics for a scan and prints a summary.
+
+```bash
+subto diag video <scanId>
+subto diag video <scanId> --server https://subto.one
+```
+
+Options:
+
+- `--server <url>` overrides the server host base.
+
+## Configuration
+
+The CLI stores local configuration in:
+
+```text
+~/.subto/config.json
+```
+
+This can include:
+
+- your Subto API key
+- a local OpenRouter key
+- a local OpenRouter model
+
+## Environment variables
+
+### Subto endpoint
+
+- `SUBTO_API_BASE_URL`
+
+Accepted forms:
+
+- `https://subto.one`
+- `https://subto.one/`
+- `https://subto.one/api/v1`
+- `https://subto.one/api/v1/`
+
+### Local AI analysis
+
+- `OPENAI_API_KEY`
+- `AI_API_KEY`
+- `OPENROUTER_API_KEY`
+- `AI_MODEL`
+- `OPENAI_MODEL`
+- `OPENROUTER_MODEL`
+
+Provider behavior:
+
+- the CLI prefers `OPENAI_API_KEY` or `AI_API_KEY` first
+- if those are not set, it falls back to `OPENROUTER_API_KEY`
+- if no environment key is set, it also checks `~/.subto/config.json` for a saved OpenRouter key
+
+### Internal server key push
+
+- `INTERNAL_TASK_SECRET`
+- `X_INTERNAL_TASK_SECRET`
+
+## `.subtoignore`
+
+The upload commands support a `.subtoignore` file.
+
+Rules:
+
+- one pattern per line
+- lines starting with `#` are comments
+- `.env` is always ignored even if it is not listed
+- matching is simple path matching, not full gitignore semantics
+
+Examples:
+
+```text
 # ignore node modules and build artifacts
 node_modules
 dist
 *.lock
-# ignore specific file
+
+# ignore a specific file
 secret.txt
 ```
 
-- AI provider: The CLI prefers `OPENAI_API_KEY` / `AI_API_KEY` for OpenAI calls; if not present it will fall back to `OPENROUTER_API_KEY`. To pick a specific model set `AI_MODEL` (example: `openai/gpt-oss-120b:free` or `gpt-4o-mini`).
+## Notes
+
+- The CLI will also try to load `.env` from the CLI directory, the current working directory, and your home directory when `dotenv` is available.
+- This package is a production CLI and intentionally omits development instructions.
+
+## Security
 
-Security note: Do not commit secrets. If sensitive keys are accidentally present, rotate them immediately. The `subto upload` tool attempts to avoid printing secret values; it will report their presence and recommend remediation.
+Do not commit secrets. If sensitive keys are accidentally present, rotate them immediately. The local analysis flow attempts not to print secret values directly; it reports their presence and recommends remediation instead.

package/dist/package/index.js

@@ -11,7 +11,7 @@ const chalk = (_chalk && _chalk.default) ? _chalk.default : _chalk;
 const CONFIG_DIR = path.join(os.homedir(), '.subto');
 const CONFIG_PATH = path.join(CONFIG_DIR, 'config.json');
 const DEFAULT_API_BASE = 'https://subto.one';
-const CLIENT_META = { name: 'subto-cli', version: '9.0.2' };
+const CLIENT_META = { name: 'subto-cli', version: '9.0.3' };
 
 function configFilePath() { return CONFIG_PATH; }
 
@@ -167,7 +167,7 @@ function printAccountSummary(payload) {
 
 async function run(argv) {
   const program = new Command();
-  program.name('subto').description('Subto CLI — wrapper around Subto.One API').version(CLIENT_META.version || '9.0.2');
+  program.name('subto').description('Subto CLI — wrapper around Subto.One API').version(CLIENT_META.version || '9.0.3');
 
   program.command('login').description('Store your API key in ~/.subto/config.json').action(async () => {
     try {

package/index.js

@@ -11,7 +11,7 @@ const chalk = (_chalk && _chalk.default) ? _chalk.default : _chalk;
 const CONFIG_DIR = path.join(os.homedir(), '.subto');
 const CONFIG_PATH = path.join(CONFIG_DIR, 'config.json');
 const DEFAULT_API_BASE = 'https://subto.one/api/v1';
-const CLIENT_META = { name: 'subto-cli', version: '9.0.2' };
+const CLIENT_META = { name: 'subto-cli', version: '9.0.3' };
 const cp = require('child_process');
 
 // Normalize SUBTO API base so callers can set either
@@ -612,7 +612,59 @@ async function startChatREPL(scanData){
 
 async function run(argv) {
   const program = new Command();
-  program.name('subto').description('Subto CLI — wrapper around Subto.One API').version(CLIENT_META.version || '9.0.2');
+  program.name('subto').description('Subto CLI — wrapper around Subto.One API').version(CLIENT_META.version || '9.0.3');
+  program.addHelpText('after', `
+
+Common commands:
+  subto login
+    Store your Subto API key in ~/.subto/config.json.
+
+  subto account
+  subto account --json
+    Show your account name, email, API call count, scan count, and member-since date.
+
+  subto scan <url>
+  subto scan <url> --wait
+  subto scan <url> --no-wait
+  subto scan <url> --json
+  subto scan <url> --chat
+    Request a remote scan for a URL. Polling happens automatically when the server queues the scan unless you pass --no-wait.
+
+  subto scan upload [dir]
+  subto scan upload [dir] --wait
+    Upload sampled files from a directory to the server and create a scan. Respects .subtoignore and always ignores .env.
+
+  subto chat [scanId]
+  subto --chat
+    Start the local interactive assistant for an existing scan, or prompt for a scan id / JSON file.
+
+  subto upload [dir]
+  subto upload [dir] --max-files 300 --max-bytes 5242880
+    Run local AI analysis on sampled project files without uploading them to the Subto server.
+
+  subto upload key
+  subto upload key <openrouter-api-key>
+    Store a local OpenRouter key and model in ~/.subto/config.json for local AI analysis.
+
+  subto server-set-ai-key [key] --secret <internal-secret>
+    Push an AI provider key to a running server via /internal/set-ai-key.
+
+  subto diag video <scanId>
+    Fetch server-side video debug details for a scan and print a summary.
+
+Environment:
+  SUBTO_API_BASE_URL     Override the API base. Accepts either a host URL or an /api/v1 URL.
+  OPENAI_API_KEY         Use OpenAI for local AI analysis.
+  AI_API_KEY             Alternate name for OPENAI_API_KEY.
+  OPENROUTER_API_KEY     Use OpenRouter for local AI analysis.
+  AI_MODEL               Override the model used for local AI analysis.
+  INTERNAL_TASK_SECRET   Default secret for subto server-set-ai-key.
+
+Notes:
+  - The CLI stores config in ~/.subto/config.json.
+  - The CLI will also load .env from the CLI directory, the current working directory, and your home directory when dotenv is available.
+  - Use subto help <command> for command-specific usage.
+`);
   program.option('-v, --verbose', 'Show verbose HTTP logs');
   program.option('--debug', 'Show debug HTTP headers and responses');
   program.option('--chat', 'Start local AI assistant (no command required)');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "subto",
-  "version": "9.0.2",
+  "version": "9.0.3",
   "description": "Subto CLI — thin wrapper around the Subto.One API",
   "bin": {
     "subto": "bin/subto.js"