npm package

@brainfog/cypher-cli

Security scanner CLI for JavaScript & TypeScript — zero config, run it with npx.

latest

v1.0.0

npx @brainfog/cypher-cli --help

Get started

Three commands, in this order.

01 — Install

npm install -D @brainfog/cypher-cli

Optional — npx fetches the CLI on demand. Install it locally to pin the version and skip the download.

02 — Sign in

npx @brainfog/cypher-cli login

Prompts for your dashboard email and password, then for the pairing code shown on your dashboard. Required: every scan command refuses to run without it.

03 — Scan

npx @brainfog/cypher-cli scan .

Static scan of the current folder, then the AI analysis menu. Writes a report.

Install

Nothing to install — npx fetches and runs the CLI on demand. Every command must be run through npx: launched any other way the CLI stops and prints the correct command instead.

Run with npx (the only supported form)

npx @brainfog/cypher-cli --version
npx @brainfog/cypher-cli scan .

First run downloads the package; npx caches it after that.

Pin an exact version

npx @brainfog/cypher-cli@1.0.0 scan .

Project devDependency (CI)

npm install -D @brainfog/cypher-cli
npx @brainfog/cypher-cli scan .

With the package installed locally, npx resolves it from node_modules — no download.

npx required

Running the bare cypher binary — from a global install, or by calling the file directly — exits with code 2 and this message:

Cypher must be run with npx.

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

Quick start

cd your-project

            npx @brainfog/cypher-cli login   # email + password, then the dashboard pairing code
            npx @brainfog/cypher-cli scan .  # scan + AI analysis + upload to dashboard

            open ./cypher-report/report.html

~/projects/acme-dashboardlive

$ npx @brainfog/cypher-cli scan ./acme-dashboard

Commands

Full command reference

This is the complete set — it matches npx @brainfog/cypher-cli --help exactly.

npx @brainfog/cypher-cli scan

Full scan — dependencies, secrets, and routes. When you are logged in it then offers an AI analysis (review / audit / security) and uploads the result to your dashboard.

npx @brainfog/cypher-cli scan [path]                    # static scan, then the AI analysis menu
npx @brainfog/cypher-cli scan . --mode security         # pick the analysis directly (no menu)
npx @brainfog/cypher-cli scan . --format pdf --with-ai  # PDF + AI fixes for critical/high
npx @brainfog/cypher-cli scan . --mode all --format all # one PDF per analysis, plus JSON + HTML
npx @brainfog/cypher-cli scan . --no-upload             # keep it local, skip the dashboard

npx @brainfog/cypher-cli review

Lighter scan — dependencies and secrets only, skips route checks. Static only, no AI, no upload. Good default for CI and pull requests.

npx @brainfog/cypher-cli review [path] --fail-on high

npx @brainfog/cypher-cli fix

AI fix suggestion for one finding ID from report.json — root cause, patched code, and verification steps. Requires login.

npx @brainfog/cypher-cli fix --id <findingId> [path]
npx @brainfog/cypher-cli fix --id FIND-0002 -r ./cypher-report/report.json

npx @brainfog/cypher-cli explain

Plain-language explanation of one finding — summary, technical detail, business impact, attack scenario. Requires login.

npx @brainfog/cypher-cli explain --id <findingId> [path]

npx @brainfog/cypher-cli login

Sign in with your dashboard email and password, then paste the pairing code generated on the dashboard. The code is what ties this terminal to the right account, so scans land on the dashboard you are watching. The session is stored in ~/.cypher/credentials.json and reused until you log out.

npx @brainfog/cypher-cli login
npx @brainfog/cypher-cli login --force    # sign in again as a different account

npx @brainfog/cypher-cli logout

End the session on the server and delete the stored credentials. Scans refuse to run afterwards until you sign in again.

npx @brainfog/cypher-cli logout

npx @brainfog/cypher-cli whoami

Show which account the stored session belongs to and which API it points at.

npx @brainfog/cypher-cli whoami

npx @brainfog/cypher-cli usage

Your AI token usage, remaining quota, and a per-command breakdown. Requires login.

npx @brainfog/cypher-cli usage

npx @brainfog/cypher-cli graph

Export the project dependency and import graph as JSON — to stdout, or to a file with -o.

npx @brainfog/cypher-cli graph .
npx @brainfog/cypher-cli graph . -o graph.json

Options

Flags for npx @brainfog/cypher-cli scan:

Flag	Description
-f, --format	json · html · pdf · both · all (default: both)
-o, --output	Output dir (default: <path>/cypher-report)
--fail-on	Exit 3 at severity threshold — critical · high · medium · low
--mode	AI analysis: review · audit · security · all (skips the interactive menu)
--depth	AI scan depth: quick · standard · thorough (default: quick)
--concurrency	Parallel AI requests, 1–32 — raise it on a paid tier for speed
--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	API base URL (or env CYPHER_API_URL)
--token	JWT access token (or env CYPHER_TOKEN) — for CI, instead of `npx @brainfog/cypher-cli login`
--project-id	Upload target (or env CYPHER_PROJECT_ID). Default: a project named after the folder

review takes --format, --output, and --fail-on. fix and explain take --id <findingId>, -r, --report <file>, --api-url, and --token. graph takes -o, --output <file>. login takes --force.

AI analysis

AI runs on the CYPHER backend, so it needs a session rather than your own provider key — run npx @brainfog/cypher-cli login once and the CLI handles the rest. There is no AI API key to set locally. Logged out, scan still writes a full static report.

In an interactive terminal, scan finishes the static checks and then offers a menu:

Scan complete — choose an analysis to run
  Code Review    — bugs, quality, maintainability
  Code Auditing  — dependencies, config, robustness
  Security       — vulnerabilities, secrets, auth   (default)
  All three      — one PDF each

Pick directly (or in CI / non-interactive shells) with --mode:

npx @brainfog/cypher-cli scan . --mode review     # code review
npx @brainfog/cypher-cli scan . --mode audit      # code auditing
npx @brainfog/cypher-cli scan . --mode security   # security
npx @brainfog/cypher-cli scan . --mode all        # all three, one PDF per analysis

The AI reads your source files, reports issues with concrete fixes, and embeds them in the PDF. --depth controls how many files are analyzed (the most security-relevant first):

Depth	Best for
quick	Default — fast, fewest files (CI-friendly)
standard	Balanced coverage
thorough	Full audit — most files

Drop a .cypher.json in your project root to tune prioritization: include_dirs, exclude_dirs, include_files, max_files, depth. Check what a run cost with npx @brainfog/cypher-cli usage.

Dashboard sync

Once you are logged in, every scan uploads itself to your dashboard automatically — no token to copy, no project to create first. A project named after the folder is created on demand.

npx @brainfog/cypher-cli login
npx @brainfog/cypher-cli scan .                       # scans, then uploads

npx @brainfog/cypher-cli scan . --no-upload           # keep this run local
npx @brainfog/cypher-cli scan . --project-id <id>     # upload into a specific project

For CI, where there is no interactive terminal to sign in with, pass --token or set CYPHER_TOKEN instead.

CI / GitHub Actions

Add to any pipeline — no config file in the repo required.

# .github/workflows/security.yml
name: CYPHER scan
on: [push, pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
      - run: npx @brainfog/cypher-cli scan . --format json --fail-on high --no-upload

Exit code 3 fails the job when high-or-worse findings exist. Use critical for stricter gates. Drop --no-upload and set CYPHER_TOKEN as a secret if you want CI runs on the dashboard.

Reports

./cypher-report/
  report.json
  report.html
  report.pdf     # when --format pdf or all

Choose output with --format (json · html · pdf · both · all). Add --with-ai to embed AI fix suggestions for critical/high findings directly in the PDF. Finding IDs in report.json power fix and explain.

Environment

All optional — npx @brainfog/cypher-cli login covers the normal case. These are read from the environment or a .env in the current directory.

CYPHER_API_URL=https://cypherapi.brainfogagency.com  # override the backend
CYPHER_TOKEN=                                        # session token, for CI
CYPHER_PROJECT_ID=                                   # default upload target
CYPHER_BATCH_MAX_CALLS=10                            # cap on AI fix calls per scan
CYPHER_NO_INK=1                                      # plain output, no interactive UI
CYPHER_ALLOW_DIRECT=1                                # bypass the npx-only guard

There is no GROQ_API_KEY or OPENAI_API_KEY to set — AI requests are proxied through the CYPHER backend, which holds the provider keys. The CLI never stores one.

Exit codes

0	Clean — no findings
1	Findings found
2	Error — including “not launched through npx”
3	--fail-on threshold hit
4	Not logged in — run `npx @brainfog/cypher-cli login`
5	Access blocked (403)
6	Rate limit or token quota exceeded (429)