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.

Upgrading from an older version?

CodeSherlock CLI v1.2.1 introduced a new authentication flow, and tokens issued by older versions no longer work. If you used the CLI before this change:

  1. Update to the latest version: npm install -g @codesherlock/codesherlock-cli@latest
  2. Generate a new token from the dashboard.
  3. Re-authenticate: codesherlock auth <your-cli-token>

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 CLI token (see Step 2: Get Your CLI Token)

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 CLI Token​

  1. Visit https://codesherlock.ai/login and sign in or create an account.
  2. Open https://codesherlock.ai/auth-tokens.
  3. Generate or copy your CLI token.
  4. Save it securely and treat it like a password.

Note: CLI tokens expire 14 days after they are generated. When your token expires, the CLI will tell you — just regenerate a new one from the same page.

Note: A token is bound to the device it was first used on. Using it on a different machine will fail — regenerate the cli token from the same page and re-authenticate.

Step 3: Authenticate Once​

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

codesherlock auth <your-cli-token>

This stores the token, and all subsequent analyze runs pick it up automatically.

Token resolution for analyze:

--api-key flag

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

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

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 <token>    Token for this run (overrides saved keychain token)
  --output <format>    Output format: markdown or json (default: markdown)
  -h, --help           Display help
  -V, --version        Display version

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

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 authentication token found
Run codesherlock auth <your-cli-token> first, or pass --api-key <token> directly.

This token has expired
Your token is no longer valid. Regenerate a new token from the dashboard and re-run codesherlock auth <your-cli-token>.

This token is bound to a different device
Tokens are tied to the device they were first used on. Regenerate a token on the machine where you are running the CLI.

Unable to validate or save authentication token
Either the backend could not be reached to validate the token, or your machine denied keychain access. Check your connection, enable keychain permissions, then re-run codesherlock auth <your-cli-token>.

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​

  • Tokens expire 14 days after generation — regenerate a new one from the dashboard when yours stops working
  • Code is sent to the CodeSherlock backend over HTTPS for analysis
  • Never commit your token to version control
  • If you believe your token has been compromised, regenerate it immediately from the dashboard

Support​