Skip to main content

CodeSherlock CLI - Installation & Usage Guide

CodeSherlock CLI lets you run AI-powered code analysis directly from your terminal, with no IDE or MCP client required. Use it in pre-commit hooks, or any workflow where you need security and quality checks from the command line. Use it in autonomous AI DLC workflows to orchestrate your coding, code review, deployment in coding AI Agents like Claude Code, Cursor etc.

Key Features​

Analyze the Latest Commit​

Run analysis on files changed in the most recent commit.

Analyze Uncommitted Changes​

Scan staged and unstaged files before you commit.

Security Framework Coverage​

Choose focused analysis modes including OWASP and CWE-based checks.

CI-Friendly JSON Output​

Emit machine-readable JSON to stdout for scripts and pipelines.

Prerequisites​

Quick checklist before you begin:

  • Node.js 16 or later
  • npm 7 or later
  • A Git repository with committed or staged changes to analyze
  • A CodeSherlock API key (see Step 2: Get Your API Key)

Step 1: Install the CLI​

Install globally so the codesherlock command is available anywhere on your system:

npm install -g @codesherlock/codesherlock-cli

Verify installation:

codesherlock --version

Step 2: Get Your API Key​

  1. Visit https://codesherlock.ai/login and sign in or create an account.
  2. Open https://codesherlock.ai/codesherlock-mcp-server/mcp/api/key.
  3. Generate or copy your API key.
  4. Save it securely and treat it like a password.

Step 3: Authenticate Once​

Save your API key once so you do not need to pass it on every command:

codesherlock auth <your-api-key>

This stores the key all subsequent analyze runs pick it up automatically.

API key resolution for analyze:

--api-key flag

Use a different key for one run without overwriting your saved key:

codesherlock analyze --api-key <your-api-key>

Step 4: Analyze Your Code​

Analyze the last commit​

codesherlock analyze

Analyzes files changed in your most recent commit in the current directory.

Analyze uncommitted changes​

codesherlock analyze --uncommitted

Analyzes staged and unstaged changes that have not been committed yet.

Analyze a different repository​

codesherlock analyze --directory /path/to/your/repo

Points the CLI to any Git repository on your machine.

Choose an analysis focus​

codesherlock analyze --factor owasp
FactorWhat it checks
power_analysisSecurity, quality, and compliance combined (default)
owaspOWASP Top 10 vulnerabilities
cwe_mitreCWE/MITRE weakness catalog
cwe_kevCISA Known Exploited Vulnerabilities

Output format​

By default, results are printed as formatted Markdown with color-coded severity labels.

For machine-readable output (CI pipelines, scripting):

codesherlock analyze --output json

CLI Options​

codesherlock analyze [options]

Options:
  --uncommitted        Analyze staged/unstaged changes instead of last commit
  --directory <path>   Path to the Git repository (default: current directory)
  --factor <name>      Analysis focus: power_analysis, owasp, cwe_mitre, cwe_kev
                       (default: power_analysis)
  --api-key <key>      API key for this run (overrides saved keychain key)
  --output <format>    Output format: markdown or json (default: markdown)
  -h, --help           Display help
  -V, --version        Display version

Examples​

# Authenticate once
codesherlock auth cs_mcp_abc123

# Quick scan of last commit
codesherlock analyze

# Scan uncommitted work before committing
codesherlock analyze --uncommitted

# OWASP-focused scan of a specific repository
codesherlock analyze --directory ~/projects/my-app --factor owasp

Understanding the Output​

Markdown output (default)​

============================================================
  CodeSherlock Analysis Results
============================================================

File: src/auth/login.ts
------------------------------------------------------------

  Security
  Security-related vulnerabilities and risks.

  HIGH     Hardcoded credentials found
  Lines: 12-14
  Problem:
  | const DB_PASSWORD = "supersecret123";
  Solution: Use environment variables instead.
  Fix:
  | const DB_PASSWORD = process.env.DB_PASSWORD;

============================================================
  1 issue found.
============================================================

Severity levels​

LabelMeaning
CRITICALMust fix immediately, actively exploitable
HIGHFix before merging, serious risk
MEDIUMFix soon, moderate risk
LOWBest-practice improvement

JSON output​

The JSON output is an array of result objects, one per analyzed file:

[
  {
    "file_name": "src/auth/login.ts",
    "language": "ts",
    "analysis": [
      {
        "characteristic": "Security",
        "description_of_characteristic": "...",
        "issue_items": [
          {
            "severity": "HIGH",
            "issue": "Hardcoded credentials found",
            "solution": "Use environment variables instead.",
            "start_line": 12,
            "end_line": 14,
            "issue_code_snippet": "const DB_PASSWORD = \"supersecret123\";",
            "solution_code_snippet": "const DB_PASSWORD = process.env.DB_PASSWORD;"
          }
        ]
      }
    ]
  }
]

Troubleshooting​

No API key found
Run codesherlock auth <your-api-key> first, or pass --api-key <key> directly.

Unable to securely save API key in the OS keychain
Your machine denied keychain access. Re-run codesherlock auth <your-api-key> after enabling keychain permissions.

Network error: fetch failed
Check your internet connection and verify BACKEND_API_URL is reachable. Requests are not retried automatically by the CLI.

No file changes found
Make sure you have at least one committed change, or use --uncommitted for staged/unstaged changes.

Too many files
Analysis supports a maximum of 20 changed files per run. Split large commits into smaller ones, or use --uncommitted to analyze a subset of changes.

Security Notes​

  • Your API key is stored in your OS keychain
  • Code is sent to the CodeSherlock backend over HTTPS for analysis
  • Never commit your API key to version control
  • If you believe your key has been compromised, regenerate it immediately from the dashboard

Support​