@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 CLI token (prefixed cs_cli_) — get one here

Installation

npm install -g @codesherlock/codesherlock-cli

Verify:

codesherlock --version

Quick Start

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

# 2. Analyze the last commit
codesherlock analyze

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

Authentication

Generate a token from https://codesherlock.ai/auth-tokens and select the CLI channel. CLI tokens are prefixed cs_cli_.

CLI and MCP tokens are not interchangeable. The CLI accepts only CLI-channel tokens (cs_cli_). Passing an MCP token (cs_mcp_) is rejected with a clear message. Generate a CLI token for the CLI.

Save it once — the token is validated with the server and, on success, stored in your OS keychain. All subsequent analyze runs pick it up automatically:

codesherlock auth <your-cli-token>

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

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

Device binding and expiry

• Each token is bound to the device it is first validated on. Using it from a different machine is rejected — regenerate a token on the machine you want to run from.
• CLI tokens expire after 14 days. When a token expires, regenerate it from the dashboard and run codesherlock auth again.

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_cli_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-cli-token> first, or pass --api-key <key> on the command.

This is an MCP-channel token (cs_mcp_...)
You passed an MCP token to the CLI. The CLI accepts only CLI-channel tokens (cs_cli_). Generate a CLI token at https://codesherlock.ai/auth-tokens.

This token is bound to a different device
Tokens are device-bound. Regenerate a token on the machine you want to run the analysis from, then run codesherlock auth again.

This token has expired
CLI tokens expire after 14 days. Regenerate the token from the dashboard and re-run codesherlock auth.

Please update your CodeSherlock CLI package
Your installed CLI is below the minimum supported version. Update with npm install -g @codesherlock/codesherlock-cli and try again.

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 token 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