@brainfog/cypher-cli

Security scanner for JavaScript and TypeScript projects — secrets, dependencies, and routes, with optional AI analysis and fix suggestions.

Install

Nothing to install — npx fetches and runs the CLI on demand:

npx @brainfog/cypher-cli --version

npx is required. Every command below starts with npx @brainfog/cypher-cli. Launched any other way — a bare cypher from a global install, or by calling the file directly — the CLI exits with code 2 and prints the command you should have run:

Cypher must be run with npx.

  You ran:       cypher scan .
  Use instead:   npx @brainfog/cypher-cli scan .

Start here

npx @brainfog/cypher-cli login      # sign in with your dashboard email + password
npx @brainfog/cypher-cli scan .     # scan the current project
npx @brainfog/cypher-cli logout     # sign out and remove stored credentials

All commands

# Full scan (dependencies, secrets, routes), then the AI analysis menu
npx @brainfog/cypher-cli scan ./my-app

# Code-review scan (dependencies + secrets only — good for CI/PRs)
npx @brainfog/cypher-cli review ./my-app

# Write a PDF report (also: json | html | both | all)
npx @brainfog/cypher-cli scan ./my-app --format pdf

# PDF report with AI fix suggestions embedded for critical/high findings
npx @brainfog/cypher-cli scan ./my-app --format pdf --with-ai

# AI-powered fix / explanation for a finding from the last report
npx @brainfog/cypher-cli fix --id <finding-id> ./my-app
npx @brainfog/cypher-cli explain --id <finding-id> ./my-app

# Session and quota
npx @brainfog/cypher-cli whoami
npx @brainfog/cypher-cli usage

# Export the project's import/dependency graph as JSON
npx @brainfog/cypher-cli graph ./my-app

Reports are written to <project>/cypher-report/ by default (override with -o <dir>).

scan options

| Option | Description | |--------|-------------| | -f, --format <fmt> | json | html | pdf | both (default) | all | | -o, --output <dir> | Report output directory | | --fail-on <severity> | Exit 3 if findings at or above critical/high/medium/low | | --mode <mode> | AI analysis: review | audit | security | all (skips the menu) | | --depth <level> | AI scan depth: quick (default) | standard | thorough | | --concurrency <n> | Parallel AI requests, 1–32 | | --with-ai | Embed AI fix suggestions for critical/high findings in the PDF | | --no-upload | Skip the dashboard upload (results upload by default when logged in) | | --api-url <url> | API base URL (or CYPHER_API_URL) | | --token <jwt> | JWT access token (or CYPHER_TOKEN) — for CI, instead of npx @brainfog/cypher-cli login | | --project-id <id> | Upload target (or CYPHER_PROJECT_ID); defaults to a project named after the folder |

Exit codes

| Code | Meaning | |------|---------| | 0 | No findings | | 1 | Findings found | | 2 | Error while running | | 3 | Findings at or above --fail-on severity | | 2 | Not launched through npx | | 4 | Not logged in — run npx @brainfog/cypher-cli login | | 5 | Access blocked (403) | | 6 | Rate limit or token quota exceeded (429) |

Environment variables

AI runs on the Cypher backend, which holds the provider keys — there is no AI API key to set locally. All of these are optional; npx @brainfog/cypher-cli login covers the normal case.

| Variable | Purpose | |----------|---------| | CYPHER_API_URL | Override the backend base URL | | CYPHER_TOKEN | Session token, for CI where there is no interactive prompt | | CYPHER_PROJECT_ID | Default upload target | | CYPHER_BATCH_MAX_CALLS | Cap on AI fix calls per scan (default 10) | | CYPHER_NO_INK | Set to 1 for plain output with no interactive UI | | CYPHER_ALLOW_DIRECT | Set to 1 to bypass the npx-only guard (for tooling that spawns the CLI directly) |

License

MIT