CLI REFERENCE

CLI Complete Reference

The CodeScan CLI brings the full AI security pipeline to your terminal. Scan any codebase, auto-fix vulnerabilities, enforce quality gates, and integrate with GitHub, Slack, and Jira — no Anthropic API key required on your end.

1. Installation

Requires Node.js 18 or later. Install globally so the codescan command is available everywhere:

npm install -g codescan-flowlog

Verify the install:

codescan --version

Run without installing (uses npx to pull the latest version each time):

npx codescan-flowlog scan --dir ./src

2. Authentication

Every command requires a CodeScan account. You only need to log in once — the session refreshes automatically.

codescan login

Prompts for your email and password (same credentials as codesscan.com). Saves your session to ~/.codescan/config.json.

codescan login

codescan logout

Removes your stored session. You will need to run codescan login again before scanning.

codescan logout

codescan whoami

Shows which account is currently logged in and whether the session is active or will auto-refresh.

codescan whoami

Auto-refresh

Sessions refresh silently in the background. As long as you use the CLI at least once every 7 days, you will never be asked to log in again.

CI/CD — CODESCAN_TOKEN env var

For pipelines where interactive login is not possible, set the CODESCAN_TOKEN environment variable with your access token. When this variable is present it takes priority over the saved session.

export CODESCAN_TOKEN=your_access_token
codescan scan --dir ./src

3. Scanning Code — `codescan scan`

Sends your source files through the 5-step AI pipeline and prints a colour-coded report. Files are scanned one by one and results appear in real time.

Scan the current directory

No arguments needed — defaults to .:

codescan scan

-d / --dir <path> — Scan a directory

Point the scanner at any directory on your machine:

codescan scan --dir ./src
codescan scan --dir /projects/my-api

-f / --file <path> — Scan a single file

Scan one specific file instead of a whole directory:

codescan scan --file ./src/auth.ts
codescan scan --file ./app.py

--enrich — Add CVE / CVSS / EPSS / CISA KEV data

After scanning, each finding is cross-referenced against the National Vulnerability Database (NVD), scored with EPSS exploit probability, and checked against the CISA Known Exploited Vulnerabilities catalog. This adds real-world risk context to every issue.

codescan scan --dir ./src --enrich

What you get with enrichment:

CVE IDs — matched CVEs from the NVD
CVSS score — industry-standard severity score (0–10)
EPSS % — probability the CVE will be exploited in the next 30 days
KEV — CISA Known Exploited: actively attacked in the wild right now

-v / --verbose — Show AI pipeline steps

Prints each step of the AI pipeline as it runs (Scan → Investigate → Revalidate → Enrich → Export) and shows all findings per file, not just the top 3:

codescan scan --dir ./src --verbose

-o / --output <path> — Save a JSON report

Writes the full structured report to a file after the scan completes. The JSON includes every finding with all metadata, CVE details, EPSS scores, and per-file results:

codescan scan --dir ./src --enrich --output report.json

--no-banner — Suppress the ASCII banner

Hides the CODESCAN ASCII art header. Useful in CI logs where you want clean output:

codescan scan --dir ./src --no-banner

4. Understanding Scan Results

Each file prints one of three statuses:

✓ CLEAN

No vulnerabilities found in this file.

✗ VULN

One or more vulnerabilities found. The count and highest severity are shown.

⚠ SKIP

File was skipped — too large (>100 KB) or not a supported file type.

Severity levels

CRITICAL

Exploitable right now with high impact. Fix immediately.

HIGH

Serious vulnerability. Should be fixed before next release.

MEDIUM

Real issue but harder to exploit or lower impact.

LOW

Minor issue or defence-in-depth improvement.

INFO

Informational — no direct risk but worth reviewing.

CVSS score

The Common Vulnerability Scoring System (CVSS) rates severity from 0 to 10. Scores are colour-coded: 7.0–8.9 HIGH, 9.0–10 CRITICAL, 4.0–6.9 MEDIUM.

EPSS probability

Exploit Prediction Scoring System — the percentage chance that this specific CVE will be exploited in the wild within the next 30 days. A score above 10% is considered high-priority.

CISA KEV badge

KEV means the US Cybersecurity and Infrastructure Security Agency has confirmed this CVE is being actively exploited in real attacks right now. Any KEV finding exits the CLI with code 2 and should be patched immediately.

5. AI Auto-Fix — `codescan fix`

Scans a file, identifies all auto-fixable vulnerabilities, generates AI patches in context of your actual code, and writes the fixed version.

Fix a file in place

The original file is overwritten with the patched version:

codescan fix ./src/auth.ts

-o / --output <path> — Fix to a new file

Writes the fixed version to a different path, leaving the original untouched. Use this to review the diff before committing:

codescan fix ./src/auth.ts --output ./src/auth.fixed.ts

Then compare:

diff ./src/auth.ts ./src/auth.fixed.ts

What gets fixed

Only findings where the AI has high confidence in a safe patch are marked auto-fixable. Findings that require architectural changes or human judgement are shown in the report but not auto-patched.

6. Exit Codes & CI/CD

CodeScan uses exit codes to integrate cleanly with any CI/CD pipeline:

exit 0

No vulnerabilities found at or above the threshold. Pipeline passes.

exit 1

Vulnerabilities found at or above --fail-on severity. Pipeline fails.

exit 2

CISA KEV finding detected. Always fails regardless of --fail-on.

--fail-on <severity> — Set the failure threshold

Controls which severity level triggers exit code 1. Default is high.

# Fail only on critical (most permissive)
codescan scan --fail-on critical

# Fail on high or above (default — recommended)
codescan scan --fail-on high

# Fail on medium or above
codescan scan --fail-on medium

# Fail on any finding
codescan scan --fail-on low

GitHub Actions example

name: CodeScan Security
on: [push, pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install CodeScan
        run: npm install -g codescan-flowlog

      - name: Run security scan
        run: codescan scan --dir ./src --enrich --fail-on high --no-banner --output report.json
        env:
          CODESCAN_TOKEN: ${{ secrets.CODESCAN_TOKEN }}

      - name: Upload report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: codescan-report
          path: report.json

Add your token to GitHub: Repository → Settings → Secrets → Actions → New secret → name it CODESCAN_TOKEN.

To get your token value, run codescan login then open ~/.codescan/config.json and copy the access_token field.

7. Supported Languages & Files

The following file types are scanned automatically:

TypeScript  .ts  .tsx
JavaScript  .js  .jsx  .mjs  .cjs
Python      .py
Ruby        .rb
Go          .go
Java        .java
Kotlin      .kt
Swift       .swift
C / C++     .c  .cpp  .cc  .h  .hpp
C#          .cs
PHP         .php
Rust        .rs
Shell       .sh  .bash
SQL         .sql
Config      .yaml  .yml  .json  .tf  .hcl

These directories are always ignored:

node_modules   .git       .next    dist
build          out        .turbo   coverage
__pycache__    venv       .venv    vendor
target         .cache

Files larger than 100 KB are skipped automatically and shown as SKIP in the output.

8. JSON Report Format

When you use --output report.json, the file contains the full scan report:

{
  "id": "scan_1715000000000",
  "timestamp": "2026-05-12T20:00:00.000Z",
  "target": "/projects/my-app/src",
  "totalFiles": 12,
  "scannedFiles": 11,
  "skippedFiles": 1,
  "totalVulnerabilities": 3,
  "criticalCount": 1,
  "highCount": 2,
  "mediumCount": 0,
  "lowCount": 0,
  "infoCount": 0,
  "kevCount": 0,
  "scanDuration": 34210,
  "results": [
    {
      "file": "/projects/my-app/src/auth.ts",
      "language": "typescript",
      "linesOfCode": 120,
      "scanDuration": 8400,
      "vulnerabilities": [
        {
          "id": "vuln_001",
          "title": "SQL Injection via unsanitised input",
          "severity": "critical",
          "category": "Injection",
          "line": 42,
          "description": "...",
          "recommendation": "...",
          "cwe": "CWE-89",
          "owasp": "A03:2021",
          "confidence": "high",
          "fixAvailable": true,
          "cveIds": ["CVE-2023-1234"],
          "cvssScore": 9.8,
          "epssScore": 0.043,
          "cisaKev": false
        }
      ]
    }
  ]
}

5. `codescan usage` — Plan & Credits

Shows your current subscription tier, how many files you have scanned this month, and how many remain in your allowance.

codescan usage

# Output example:
Plan      : Pro
Files used: 87 / 400 this period
Remaining : 313
Period end: 2026-06-01

6. `codescan history` — Scan Trend

Lists your last N scan results with score, grade, vulnerability counts, and target. Shows a trend line comparing your most recent score against the oldest in the window.

codescan history           # last 10 scans (default)
codescan history --limit 20  # last 20 scans

# Output:
DATE                   SCORE    GRADE  VULNS  CRIT  TARGET
────────────────────────────────────────────────────────────
14 May 2026 09:15      88/100   B      3      0     ./src
13 May 2026 14:30      72/100   C      9      0     ./src
12 May 2026 11:00      61/100   D      14     1     ./src
Trend: ↑ +27 pts vs 3 scans ago

7. `codescan fix` — Single-File AI Fix

Scans one file, generates AI patches for all auto-fixable vulnerabilities in context, and writes the result. Requires Starter+ plan.

Fix a file in place

codescan fix ./src/auth.ts

`-o / --output <path>` — Write fix to a new file

Leaves the original untouched. Compare the diff before committing:

codescan fix ./src/auth.ts --output ./src/auth.fixed.ts
diff ./src/auth.ts ./src/auth.fixed.ts

What gets fixed

Only findings where the AI has high confidence in a safe, minimal patch are marked auto-fixable. Findings that require architectural changes or human judgement are reported but not auto-patched.

8. `codescan autofix` — Batch AI Fix

Scans an entire directory, generates AI patches for all matching findings, and writes fixes back to disk automatically — no prompts, no manual steps. This is the bot-on-your-filesystem mode: it does what CodescanBot does in the web UI, but across your whole codebase.

Flag	Default	Description
--dir <path>	.	Directory to scan and fix recursively
--severity <level>	high	Minimum severity to fix: critical \| high \| medium \| low
--max <n>	20	Maximum number of files to fix in a single run
--dry-run	false	Preview what would be fixed without writing any files
-u, --url <url>	codesscan.com	Override API base URL (self-hosted instances)

Examples

# Fix all high+ findings in ./src (writes to disk)
codescan autofix --dir ./src

# Fix only critical findings
codescan autofix --dir ./src --severity critical

# Preview without writing anything
codescan autofix --dir ./src --dry-run

# Fix medium+ findings, up to 50 files
codescan autofix --dir ./src --severity medium --max 50

How it works

◈ CodeScan AutoFix
  Target   : /projects/my-api/src
  Severity : high+
  Mode     : apply fixes

✖ src/auth.ts — 2 fixable finding(s)
  CRITICAL  SQL Injection via unsanitised input
  HIGH      Missing rate limiting on login endpoint
  ✓ Fixed 2 issue(s) in src/auth.ts

✖ src/upload.ts — 1 fixable finding(s)
  HIGH      Unrestricted file upload type
  ✓ Fixed 1 issue(s) in src/upload.ts

────────────────────────────────────────────────────────────
AUTOFIX SUMMARY
────────────────────────────────────────────────────────────
  Files scanned  : 12
  Files fixed    : 2

9. Quality Gates — `--gate`

Add --gate to any scan to enforce a hard pass/fail verdict. The gate exits with code 1 if any threshold is violated, blocking CI merges automatically.

codescan scan --dir ./src --gate

# Custom thresholds
codescan scan --dir ./src --gate \
  --gate-max-critical 0   \
  --gate-max-high 2       \
  --gate-max-medium 5     \
  --gate-min-score 80

Flag	Default	Description
--gate	off	Enable quality gate enforcement
--gate-max-critical <n>	0	Maximum allowed critical findings
--gate-max-high <n>	3	Maximum allowed high findings
--gate-max-medium <n>	10	Maximum allowed medium findings
--gate-min-score <n>	70	Minimum required security score (0–100)

Persist gate config in .codescanrc.json at project root so you don't repeat flags every run:

// .codescanrc.json
{
  "gate": {
    "maxCritical": 0,
    "maxHigh": 2,
    "maxMedium": 5,
    "minScore": 80
  }
}

10. Integration Flags

--pr-comment — GitHub PR comment

Posts a formatted scan summary directly on the open PR. Reads GITHUB_TOKEN, GITHUB_REPOSITORY, and the PR number from GITHUB_REF automatically in GitHub Actions.

codescan scan --dir ./src --pr-comment
# env: GITHUB_TOKEN, GITHUB_REPOSITORY, GITHUB_REF (auto-set in Actions)

--sarif-out <path> — SARIF export (Starter+)

Writes a SARIF 2.1.0 file. Upload to GitHub Security tab to see findings inline on the diff.

codescan scan --dir ./src --sarif-out results.sarif

--compliance-out <path> — Compliance HTML report (Pro+)

Generates an HTML report mapping findings to OWASP Top 10, SOC2, and PCI-DSS requirements.

codescan scan --dir ./src --compliance-out compliance.html

--save-history — Save to account history

Stores the scan result in your CodeScan account for trend tracking and regression diff. The web scanner saves automatically; the CLI requires this flag.

codescan scan --dir ./src --gate --save-history

--slack-webhook <url> — Slack notification

Posts a Block Kit message to your Slack channel after the scan. Set the URL as an environment variable to keep it out of command history.

# Via flag
codescan scan --dir ./src --slack-webhook https://hooks.slack.com/services/XXX/YYY/ZZZ

# Via environment variable (recommended)
export SLACK_WEBHOOK_URL=https://hooks.slack.com/services/XXX/YYY/ZZZ
codescan scan --dir ./src

--jira-* — Create Jira tickets

Creates one Bug ticket per finding at or above the configured severity.

codescan scan --dir ./src \
  --jira-url https://acme.atlassian.net \
  --jira-project SEC \
  --jira-email you@acme.com \
  --jira-token your-api-token \
  --jira-severity high \
  --jira-max 10

# Or set all via env vars:
# JIRA_BASE_URL, JIRA_PROJECT, JIRA_EMAIL, JIRA_API_TOKEN

Jira flag	Env var	Description
--jira-url <url>	JIRA_BASE_URL	Jira Cloud base URL
--jira-project <key>	JIRA_PROJECT	Project key, e.g. SEC
--jira-email <email>	JIRA_EMAIL	Atlassian account email
--jira-token <token>	JIRA_API_TOKEN	Atlassian API token
--jira-severity <sev>	—	Minimum severity to ticket (default: high)
--jira-max <n>	—	Max tickets per scan (default: 10)

11. Full CI/CD Workflow

# .github/workflows/codescan.yml
name: CodeScan Security

on:
  pull_request:
  push:
    branches: [main]

jobs:
  security:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write
      pull-requests: write

    steps:
      - uses: actions/checkout@v4

      - name: Run CodeScan
        run: |
          npx codescan-flowlog scan \
            --dir ./src \
            --gate \
            --sarif-out results.sarif \
            --compliance-out compliance.html \
            --pr-comment \
            --save-history \
            --fail-on high
        env:
          CODESCAN_TOKEN:    ${{ secrets.CODESCAN_TOKEN }}
          GITHUB_TOKEN:      ${{ secrets.GITHUB_TOKEN }}
          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
          JIRA_BASE_URL:     ${{ secrets.JIRA_BASE_URL }}
          JIRA_PROJECT:      SEC
          JIRA_EMAIL:        ${{ secrets.JIRA_EMAIL }}
          JIRA_API_TOKEN:    ${{ secrets.JIRA_API_TOKEN }}

      - name: Upload SARIF to GitHub Security tab
        if: always()
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif

      - name: Upload compliance report artifact
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: compliance-report
          path: compliance.html

12. Exit Codes

exit 0

Scan clean — no findings at or above the --fail-on threshold. CI passes.

exit 1

Findings at or above --fail-on severity. Quality gate failed. CI blocks merge.

exit 2

CISA KEV finding detected — actively exploited in the wild. Always fails regardless of --fail-on.

13. Supported Languages & Files

TypeScript  .ts  .tsx
JavaScript  .js  .jsx  .mjs  .cjs
Python      .py
Ruby        .rb
Go          .go
Java        .java
Kotlin      .kt
Swift       .swift
C / C++     .c  .cpp  .cc  .h  .hpp
C#          .cs
PHP         .php
Rust        .rs
Shell       .sh  .bash
SQL         .sql
Config      .yaml  .yml  .json  .tf  .hcl

Always-ignored directories: node_modules .git .next dist build out coverage __pycache__ venv vendor target. Files over 100 KB are skipped.

14. Full Command Quick Reference

# ── Auth ──────────────────────────────────────────────────────────────
codescan login                            # Interactive login
codescan logout                           # Remove stored session
codescan whoami                           # Show current account
codescan usage                            # Plan + remaining credits

# ── Account & History ──────────────────────────────────────────────────
codescan history                          # Last 10 scans + trend
codescan history --limit 20              # Last 20 scans

# ── Scanning ───────────────────────────────────────────────────────────
codescan scan                             # Scan current directory
codescan scan --dir ./src                 # Scan directory
codescan scan --file app.py              # Scan single file
codescan scan --enrich                    # Add CVE/CVSS/EPSS/KEV data
codescan scan --verbose                   # Show AI pipeline steps
codescan scan --no-banner                 # Suppress ASCII banner
codescan scan --output report.json        # Save JSON report

# ── Severity / CI Threshold ────────────────────────────────────────────
codescan scan --fail-on critical          # exit 1 on critical only
codescan scan --fail-on high              # exit 1 on high+ (default)
codescan scan --fail-on medium            # exit 1 on medium+
codescan scan --fail-on low               # exit 1 on any finding

# ── Quality Gate ───────────────────────────────────────────────────────
codescan scan --gate                      # Enforce default gate
codescan scan --gate --gate-max-critical 0 --gate-max-high 2 --gate-min-score 80

# ── Export ─────────────────────────────────────────────────────────────
codescan scan --sarif-out results.sarif   # SARIF 2.1.0 (Starter+)
codescan scan --compliance-out c.html     # OWASP/SOC2/PCI-DSS HTML (Pro+)

# ── History ────────────────────────────────────────────────────────────
codescan scan --save-history              # Save result to account

# ── Integrations ───────────────────────────────────────────────────────
codescan scan --pr-comment                # Post GitHub PR comment
codescan scan --slack-webhook <url>       # Post Slack Block Kit message
codescan scan --jira-url <u> --jira-project SEC --jira-email <e> --jira-token <t>

# ── AI Fix ─────────────────────────────────────────────────────────────
codescan fix ./src/auth.ts                # Fix file in place (Starter+)
codescan fix ./src/auth.ts -o out.ts     # Fix to new file

# ── AI AutoFix (batch — writes to disk) ───────────────────────────────
codescan autofix --dir ./src              # Fix all high+ findings
codescan autofix --dir ./src --severity critical  # Critical only
codescan autofix --dir ./src --dry-run    # Preview without writing
codescan autofix --dir ./src --max 50    # Up to 50 files

# ── Help ───────────────────────────────────────────────────────────────
codescan --help                           # All commands
codescan scan --help                      # All scan flags
codescan autofix --help                   # AutoFix flags
codescan --version                        # Installed version

CLI Complete Reference

1. Installation

2. Authentication

codescan login

codescan logout

codescan whoami

Auto-refresh

CI/CD — CODESCAN_TOKEN env var

3. Scanning Code — codescan scan

Scan the current directory

-d / --dir <path> — Scan a directory

-f / --file <path> — Scan a single file

--enrich — Add CVE / CVSS / EPSS / CISA KEV data

-v / --verbose — Show AI pipeline steps

-o / --output <path> — Save a JSON report

--no-banner — Suppress the ASCII banner

4. Understanding Scan Results

Severity levels

CVSS score

EPSS probability

CISA KEV badge

5. AI Auto-Fix — codescan fix

Fix a file in place

-o / --output <path> — Fix to a new file

What gets fixed

6. Exit Codes & CI/CD

--fail-on <severity> — Set the failure threshold

GitHub Actions example

7. Supported Languages & Files

8. JSON Report Format

5. codescan usage — Plan & Credits

6. codescan history — Scan Trend

7. codescan fix — Single-File AI Fix

Fix a file in place

-o / --output <path> — Write fix to a new file

What gets fixed

8. codescan autofix — Batch AI Fix

Examples

How it works

9. Quality Gates — --gate

10. Integration Flags

--pr-comment — GitHub PR comment

--sarif-out <path> — SARIF export (Starter+)

--compliance-out <path> — Compliance HTML report (Pro+)

--save-history — Save to account history

--slack-webhook <url> — Slack notification

--jira-* — Create Jira tickets

11. Full CI/CD Workflow

12. Exit Codes

13. Supported Languages & Files

14. Full Command Quick Reference

3. Scanning Code — `codescan scan`

5. AI Auto-Fix — `codescan fix`

5. `codescan usage` — Plan & Credits

6. `codescan history` — Scan Trend

7. `codescan fix` — Single-File AI Fix

`-o / --output <path>` — Write fix to a new file

8. `codescan autofix` — Batch AI Fix

9. Quality Gates — `--gate`