Terminal Usage

Terminal Usage (PowerShell / cmd / bash)

Caspian Security is not just a VS Code extension — it's a standalone command-line scanner you can run anywhere, with no editor required. It's published to npm as caspian-security and works the same on Windows PowerShell, cmd, macOS, and Linux.

---

Install

# Zero install — runs the latest published version (any shell)
npx -y caspian-security caspian scan .

# Or install once, globally, and get the `caspian` command everywhere
npm install -g caspian-security
caspian --help

On Windows, the global install creates caspian.cmd / caspian.ps1 shims, so caspian works in both PowerShell and cmd.

---

The caspian command

One unified command fronts every capability:

caspian scan [path]        # run the security scanner (SARIF / JSON / text)
caspian git-history [path] # walk git history for leaked secrets
caspian check-updates      # npm audit + stack version checks
caspian mcp                # start the MCP server (stdio)
caspian snippet            # print a paste-ready AI-agent instruction block
caspian mcp-config         # print an MCP client config block
caspian help               # full command list
caspian --version

The original bins — caspian-scan, caspian-git-history-scan, caspian-check-updates, caspian-mcp — still work unchanged.

---

caspian scan flags

caspian scan [path]
  --format sarif|json|text        output format (default: sarif)
  --fail-on error|warning|info|never   exit-code threshold (default: error)
  --output <file>                 write to a file instead of stdout
  --include <substr,substr>       extra path substrings to include
  --exclude <substr,substr>       directory names to skip
  --max-file-size <bytes>         skip files larger than this (default: 500000)
  --baseline <file>               suppress known findings; only NEW ones gate
  --update-baseline               regenerate the baseline, then exit 0
  --changed-since <ref>           scan only files changed since <ref> (PR scope)

Exit codes

Code	Meaning
0	Clean (or everything baselined)
1	At least one finding at/above the --fail-on threshold
2	The scan failed to run (bad args, I/O error)

This makes Caspian easy to gate any pipeline — GitLab, Jenkins, CircleCI, Drone, a Git pre-commit hook, or a scheduled task.

---

Machine-readable output

--format json emits a flat, easy-to-parse structure — ideal for AI agents and custom dashboards:

{
  "issues": [
    {
      "file": "src/app.ts",
      "line": 42,
      "column": 15,
      "severity": "Error",
      "code": "CRED001",
      "category": "Secrets & Credentials",
      "message": "Hardcoded password or secret assignment",
      "suggestion": "Use environment variables or a secure secret manager...",
      "pattern": "password = \"...\""
    }
  ]
}

--format sarif (the default) emits SARIF v2.1.0 for GitHub code scanning — see SARIF Export.

---

Examples

# PowerShell: scan and copy the AI-agent snippet to the clipboard
caspian snippet --agent claude | Set-Clipboard

# PR-scope scan against a base branch, gated on errors
caspian scan . --changed-since origin/main --fail-on error

# Write SARIF for CI upload
caspian scan . --format sarif --output results.sarif

See also: AI Agent Integration, PR Scanning, SARIF Export, Getting Started.