npm package

@cypher-ai/cli

Security scanner CLI for JavaScript & TypeScript — publishable, zero config.

latest

v1.2.0

npmjs.com →node ≥ 20bin: cypher

npm install -g @cypher-ai/cli

Install

Install globally for the cypher command, or run once with npx — no global install needed.

Global (recommended)

npm install -g @cypher-ai/cli
cypher --version

Run without installing

npx @cypher-ai/cli scan .

pnpm

pnpm add -g @cypher-ai/cli
# or
pnpm dlx @cypher-ai/cli scan .

yarn

yarn global add @cypher-ai/cli
# or
yarn dlx @cypher-ai/cli scan .

Project devDependency (CI)

npm install -D @cypher-ai/cli

Then call via npx cypher or npm scripts.

Quick start

npm install -g @cypher-ai/cli

cd your-project
cypher scan .

open ./cypher-report/report.html

~/projects/acme-dashboardlive

$ cypher scan ./acme-dashboard

Commands

cypher scan

Full scan — dependencies, secrets, and routes. With an AI key it then offers a 3-way AI analysis (review / audit / security) and writes JSON, HTML, and/or PDF.

cypher scan [path]                    # static scan, then AI analysis menu
cypher scan . --mode security         # pick the analysis directly (no menu)
cypher scan . --format pdf --with-ai  # PDF + AI fixes (critical/high)
cypher scan . --format all            # json + html + pdf

cypher review

Lighter scan — dependencies and secrets only (skips routes). Ideal for CI / pull requests.

cypher review [path] --fail-on high

cypher graph

Dependency / import graph as JSON. Use -o to write to a file.

cypher graph .
cypher graph . -o graph.json

cypher fix

AI fix suggestion for a finding ID from report.json. Needs an AI key.

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

cypher explain

Plain-language explanation of a finding (summary, impact, attack scenario). Needs an AI key.

cypher explain --id <findingId> [path]

Options

Flags for cypher 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 (skips the interactive menu)
--depth	AI scan depth: quick · standard · thorough (default: quick)
--with-ai	Embed AI fix suggestions for critical/high findings in the PDF
--upload	Push results to a Cypher API server
--api-url	API base URL (or env CYPHER_API_URL)
--token	Auth token (or env CYPHER_TOKEN)
--project-id	Target project (or env CYPHER_PROJECT_ID)

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

AI analysis

With an AI key set (GROQ_API_KEY or OPENAI_API_KEY), cypher scan runs the static checks and then offers a deeper AI analysis. In an interactive terminal it shows a menu:

Scan complete. Choose an analysis to run:
  1) Code Review   — bugs, quality, maintainability
  2) Code Auditing — dependencies, config, robustness
  3) Security      — vulnerabilities, secrets, auth
Select 1-3 [3]:

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

cypher scan . --mode review     # code review
cypher scan . --mode audit      # code auditing
cypher scan . --mode security   # security

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.

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 @cypher-ai/cli scan . --format json --fail-on high

Exit code 3 fails the job when high-or-worse findings exist. Use critical for stricter gates.

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.

Upload

Sync scans to your CYPHER workspace. Get a token from the dashboard → Settings → API token, then create a project and copy its ID.

cypher scan . --upload \
  --token $CYPHER_TOKEN \
  --project-id $CYPHER_PROJECT_ID

Environment

# Workspace upload
CYPHER_API_URL=https://api.cypher.ai
CYPHER_TOKEN=
CYPHER_PROJECT_ID=

# AI (fix / explain)
GROQ_API_KEY=
AI_PROVIDER=groq
GROQ_MODEL=openai/gpt-oss-20b

Exit codes

0	Clean — no findings
1	Findings found
2	Error
3	--fail-on threshold hit