Subto CLI

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

npm install -g subto

Quick start

subto login
subto account
subto scan https://example.com basic
subto scan https://example.com full yes --wait
subto chat

Global options

-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.

subto login

subto account

Shows your current account summary.

subto account
subto account --json

Output includes:

• account name
• email
• account id
• API call count
• scan count
• member-since date

subto scan <url> <basic|full> [yes|no]

Requests a remote scan for a URL via the Subto API.

subto scan https://example.com basic
subto scan https://example.com basic --wait
subto scan https://example.com full yes
subto scan https://example.com full no --json
subto scan https://example.com full yes --chat

Arguments:

• <basic|full> is required.
• [yes|no] is required when mode is full.
• Do not provide a video argument when mode is basic.

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.

Examples:

• subto scan https://example.com basic
• subto scan https://example.com full yes
• subto scan https://example.com full no --wait

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.

subto scan upload
subto scan upload .
subto scan upload ./my-project --wait

Options:

• --wait polls until the remote analysis completes.

Behavior:

• respects .subtoignore
• always ignores .env
• uploads sampled snippets rather than full large files
• returns an uploadId and scanId

subto chat [scanId]

Starts the local interactive assistant for a scan.

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.

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.

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.

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.

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:

~/.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:

# ignore node modules and build artifacts
node_modules
dist
*.lock

# ignore a specific file
secret.txt

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

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.