@codesherlock/codesherlock-cli

CodeSherlock CLI

AI-powered code analysis from your terminal.

CodeSherlock CLI lets you run security, quality, and compliance checks on your code without an IDE or MCP client. Use it in pre-commit hooks, and autonomous AI-native coding workflows.

Features

• Analyze the latest commit — scan files changed in your most recent commit
• Analyze uncommitted changes — catch issues before you commit, on staged and unstaged files
• Framework-focused analysis — OWASP Top 10, CWE/MITRE, CISA Known Exploited Vulnerabilities, or a combined power analysis
• AI-DLC workflow ready — fits naturally into autonomous AI-native coding loops alongside tools like Claude Code
• Works anywhere — any Git repository on your machine, not just the current directory

Prerequisites

• Node.js 16 or later
• npm 7 or later
• A Git repository with committed or staged changes to analyze
• A CodeSherlock API key (get one here)

Installation

npm install -g @codesherlock/codesherlock-cli

Verify:

codesherlock --version

Quick Start

# 1. Save your API key once
codesherlock auth <your-api-key>

# 2. Analyze the last commit
codesherlock analyze

# 3. Analyze uncommitted changes before committing
codesherlock analyze --uncommitted

Authentication

Get your API key from https://codesherlock.ai/codesherlock-mcp-server/mcp/api/key.

Save it once — all subsequent analyze runs pick it up automatically:

codesherlock auth <your-api-key>

To use a different key for a single run without overwriting your saved key:

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

Your API key is stored in your OS keychain and never written to disk in plaintext.

Usage

Analyze the last commit

codesherlock analyze

Analyze uncommitted changes

codesherlock analyze --uncommitted

Analyze a different repository

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

Choose an analysis focus

codesherlock analyze --factor owasp

Factor	What it checks
power_analysis	Security, quality, and compliance combined (default)
owasp	OWASP Top 10 vulnerabilities
cwe_mitre	CWE/MITRE weakness catalog
cwe_kev	CISA Known Exploited Vulnerabilities

JSON output for CI/scripting

codesherlock analyze --output json

Options Reference

codesherlock analyze [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 key)
  --output <format>    Output format: markdown | json (default: markdown)
  -h, --help           Display help
  -V, --version        Display version

Output

Markdown (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

Label	Meaning
CRITICAL	Must fix immediately — actively exploitable
HIGH	Fix before merging — serious risk
MEDIUM	Fix soon — moderate risk
LOW	Best-practice improvement

JSON

[
  {
    "file_name": "src/auth/login.ts",
    "language": "ts",
    "analysis": [
      {
        "characteristic": "Security",
        "description_of_characteristic": "Security-related vulnerabilities and risks.",
        "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;"
          }
        ]
      }
    ]
  }
]

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

# Pipe JSON results into jq
codesherlock analyze --output json | jq '.[].analysis[].issue_items[].severity'

Troubleshooting

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

Unable to securely save API key in the OS keychain
Your machine denied keychain access. Enable keychain permissions and re-run codesherlock auth.

Network error: fetch failed
Check your internet connection. Requests are not retried automatically.

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

Too many files
Analysis supports up to 20 changed files per run. Split large commits or use --uncommitted to target a subset.

Security

• API key is stored in your OS keychain, not in plaintext
• Code is transmitted to the CodeSherlock backend over HTTPS
• Never commit your API key to version control
• If your key is compromised, regenerate it immediately from the dashboard

How to integrate CodeSherlock in AI-DLC workflow :

Demo video : https://youtu.be/c55BcFvonl4?si=6Df8oNaL9wQeVn5w

Documentation

Full documentation: https://docs.codesherlock.ai/codesherlock-cli/cli/setup/guide

Support

• Issues and feedback: [e-mail]
• Documentation: https://docs.codesherlock.ai

License

MIT