CLI Reference¶

Complete reference for all Code Scalpel CLI commands. Every MCP tool is also accessible directly from the command line using codescalpel.

Quick Start¶

# No installation needed (recommended)
uvx codescalpel --help

# Or install globally
pip install codescalpel
codescalpel --help

# Get help for a specific command
codescalpel extract-code --help

# JSON output (supported by most commands)
codescalpel analyze myfile.py --json

Analysis Tools¶

`analyze`¶

Analyze code using AST and static analysis.

codescalpel analyze <file_path> [options]
codescalpel analyze --code "<code_string>" [options]

Option	Description
`--json, -j`	Output as JSON
`--language, -l`	Language: `python`, `javascript`, `typescript`, `java`, `c`, `cpp`, `csharp`

Examples:

codescalpel analyze src/main.py
codescalpel analyze app.js --language javascript --json
codescalpel analyze --code "def foo(): return 42"

Tier limits: Community — 1 MB files, basic AST · Pro — 10 MB, control flow · Enterprise — unlimited

`get-file-context`¶

File overview with structure analysis without reading the full content.

codescalpel get-file-context <file_path> [--json]

Examples:

codescalpel get-file-context src/models.py
codescalpel get-file-context src/api.py --json

`get-call-graph`¶

Generate a function call graph showing relationships.

codescalpel get-call-graph <file_path> [options]

Option	Description
`--format`	`mermaid` or `json`
`--output, -o`	Output file path
`--json, -j`	Full JSON response

Examples:

codescalpel get-call-graph src/main.py
codescalpel get-call-graph src/app.js --format mermaid -o graph.md

Tier limits: Community — depth 3, 50 nodes · Pro — depth 10, 500 nodes · Enterprise — unlimited

`get-symbol-references`¶

Find all references to a symbol across the project.

codescalpel get-symbol-references <symbol_name> [options]

Option	Description
`--project-root`	Project root directory
`--scope-prefix`	Filter by scope prefix
`--no-tests`	Exclude test files
`--json, -j`	JSON output

Examples:

codescalpel get-symbol-references calculate_total
codescalpel get-symbol-references UserModel --project-root /path/to/project
codescalpel get-symbol-references helper_func --no-tests

Tier limits: Community — single file · Pro — 1000 files · Enterprise — unlimited, cross-repository

`get-graph-neighborhood`¶

Get the k-hop neighborhood of a node in the call graph.

codescalpel get-graph-neighborhood <node_id> [options]

Option	Description
`--k`	Number of hops (default: 2)
`--direction`	`incoming`, `outgoing`, or `both` (default: `both`)
`--project-root`	Project root
`--json, -j`	JSON output

Examples:

codescalpel get-graph-neighborhood process_payment
codescalpel get-graph-neighborhood validate_user --k 3 --direction incoming

`get-project-map`¶

High-level project structure map with dependency visualization.

codescalpel get-project-map [options]

Option	Description
`--project-root`	Root directory
`--entry-point`	Entry point file
`--depth`	Max depth (default: 10)
`--format`	`mermaid`, `json`, or `text`

Examples:

codescalpel get-project-map
codescalpel get-project-map --entry-point src/main.py --format mermaid
codescalpel get-project-map --depth 5

`get-cross-file-dependencies`¶

Trace cross-file dependency chains.

codescalpel get-cross-file-dependencies <file_path> [options]

Option	Description
`--project-root`	Project root
`--depth`	Max dependency depth (default: 3)
`--include-external`	Include external library deps
`--json, -j`	JSON output

`crawl-project`¶

Crawl and analyze a project directory comprehensively.

codescalpel crawl-project [options]

Option	Description
`--root-path`	Root directory to crawl
`--exclude-dirs`	Directories to exclude
`--complexity-threshold`	Complexity threshold (default: 10)
`--pattern`	File pattern to match (regex or glob)
`--pattern-type`	`regex` or `glob`
`--json, -j`	JSON output

Examples:

codescalpel crawl-project
codescalpel crawl-project --exclude-dirs node_modules __pycache__ .git
codescalpel crawl-project --complexity-threshold 15

Tier limits: Community — 100 files · Pro — unlimited, parallel · Enterprise — distributed, monorepo

Extraction Tools¶

`extract-code`¶

Surgically extract a function or class by name.

codescalpel extract-code <file_path> --function <name> [options]

Option	Description
`--function, -f`	Function name (required)
`--class, -c`	Class name (for method extraction)
`--include-deps`	Include cross-file dependencies (Pro+)
`--include-context`	Include surrounding context
`--output, -o`	Output file
`--json, -j`	JSON output

Examples:

codescalpel extract-code src/utils.py --function calculate_total
codescalpel extract-code src/api.py --function process_request --include-deps
codescalpel extract-code src/models.py --function save --class User
codescalpel extract-code src/lib.py --function helper -o extracted.py

Tier limits: Community — single file, depth 0, 1 MB · Pro — cross-file deps, depth 1, 10 MB · Enterprise — unlimited, org-wide

`update-symbol`¶

Safely replace a function or class implementation.

codescalpel update-symbol <file_path> <target_name> <new_body> [options]

Option	Description
`--type`	`function`, `class`, or `method`
`--no-backup`	Skip backup
`--json, -j`	JSON output

Examples:

codescalpel update-symbol src/utils.py foo "return 42"
codescalpel update-symbol src/models.py save "self.db.commit()" --type method

`rename-symbol`¶

Safely rename a function, class, or method.

codescalpel rename-symbol <file_path> <target_name> <new_name> [options]

Option	Description
`--type`	`function`, `class`, or `method`
`--no-backup`	Skip backup
`--json, -j`	JSON output

Examples:

codescalpel rename-symbol src/utils.py calculate_sum compute_total
codescalpel rename-symbol src/models.py User UserModel --type class

Tier limits: Community — single file · Pro — cross-file, 500 files · Enterprise — unlimited, audit trail

Security Tools¶

`scan`¶

Taint-based vulnerability detection.

codescalpel scan <file_path> [--json]
codescalpel scan --code "<code_string>" [--json]

Examples:

codescalpel scan src/api.py
codescalpel scan --code "import os; os.system(user_input)"
codescalpel scan src/auth.py --json

`cross-file-security-scan`¶

Cross-file taint analysis for security vulnerabilities.

codescalpel cross-file-security-scan [options]

Option	Description
`--project-root`	Project root
`--entry-point`	Entry point file
`--max-depth`	Max analysis depth (default: 5)
`--json, -j`	JSON output

Examples:

codescalpel cross-file-security-scan
codescalpel cross-file-security-scan --entry-point src/main.py --max-depth 10

Tier limits: Community — depth 2, single entry · Pro — depth 5 · Enterprise — unlimited, whole-program

`type-evaporation-scan`¶

Detect type mismatches between frontend TypeScript and backend Python.

codescalpel type-evaporation-scan [options]

Option	Description
`--frontend-file`	TypeScript file path
`--backend-file`	Python file path
`--frontend-code`	Frontend code string
`--backend-code`	Backend code string
`--json, -j`	JSON output

Example:

codescalpel type-evaporation-scan \
  --frontend-file src/api.ts \
  --backend-file src/views.py

`unified-sink-detect`¶

Detect dangerous security sinks across multiple languages.

codescalpel unified-sink-detect "<code>" [options]

Option	Description
`--language`	Language (default: auto-detect)
`--confidence-threshold`	Threshold 0.0–1.0 (default: 0.7)
`--json, -j`	JSON output

`scan-dependencies`¶

Scan project dependencies for CVEs and security vulnerabilities.

codescalpel scan-dependencies [options]

Option	Description
`--project-root`	Project root
`--include-dev`	Include dev dependencies
`--check-security`	Check for CVEs
`--json, -j`	JSON output

Refactoring & Testing¶

`simulate-refactor`¶

Simulate a refactoring change and verify it is safe before applying.

codescalpel simulate-refactor <file_path> --changes <description> [--json]

Example:

codescalpel simulate-refactor src/api.py --changes "rename process_data to handle_request"

`generate-unit-tests`¶

Generate unit test cases using symbolic execution paths.

codescalpel generate-unit-tests <file_path> [options]

Option	Description
`--function`	Specific function to test
`--framework`	`pytest`, `unittest`, `jest`, `mocha` (default: `pytest`)
`--coverage-target`	Target coverage % (default: 80)
`--json, -j`	JSON output

Examples:

codescalpel generate-unit-tests src/utils.py
codescalpel generate-unit-tests src/api.py --function process_request --framework pytest

Tier limits: Community — 5 tests · Pro — advanced edge cases · Enterprise — unlimited, custom templates

`symbolic-execute`¶

Z3-based symbolic execution to find all execution paths.

codescalpel symbolic-execute "<code>" [options]

Option	Description
`--max-paths`	Maximum paths to explore
`--max-depth`	Maximum execution depth
`--json, -j`	JSON output

Tier limits: Community — 10 paths, depth 5 · Pro — 100 paths, depth 20 · Enterprise — unlimited

Policy & Governance¶

`validate-paths`¶

Validate import paths in a project (Docker-aware).

codescalpel validate-paths <file_path> [--fix] [--json]

`code-policy-check`¶

Check code against policy rules (SOC2, HIPAA, PCI-DSS, GDPR).

codescalpel code-policy-check <file_path> [options]

Option	Description
`--policy-dir`	Policy directory (default: `.code-scalpel`)
`--strict`	Fail on any violation
`--json, -j`	JSON output

`verify-policy-integrity`¶

Cryptographically verify policy files have not been tampered with.

codescalpel verify-policy-integrity [--policy-dir <path>] [--json]

Configuration Management¶

`init`¶

Initialize a .code-scalpel/ configuration directory, or safely add missing files to an existing one.

codescalpel init [options]

Option	Description
`--dir, -d <path>`	Target directory (default: current directory)

Behaviour:

No .code-scalpel/ — creates it with the full default scaffold (~20 files including policies, audit log, license directory, response config)
Existing .code-scalpel/ — adds only missing files; all existing customisations preserved (recommended upgrade path)

Examples:

codescalpel init                          # First-time setup
codescalpel init --dir /path/to/project   # After upgrading — add new files only

`check`¶

Audit an existing .code-scalpel/ directory and report which files are present, missing, or corrupt.

codescalpel check [options]

Option	Description
`--dir, -d <path>`	Target directory (default: current)
`--json, -j`	Machine-readable JSON output
`--fix, -F`	Add missing files before reporting (never overwrites)

Exit codes: 0 = all required files present · 1 = required files missing or invalid

Examples:

codescalpel check
codescalpel check --fix
codescalpel check --json
codescalpel check --fix --json | jq '.summary'

`verify-policies`¶

Verify cryptographic integrity of policy files using the HMAC manifest.

codescalpel verify-policies [--dir <path>] [--manifest-source file|env]

`regenerate-manifest`¶

Regenerate policy.manifest.json after modifying policy files.

codescalpel regenerate-manifest [--dir <path>] [--signed-by <name>]

Example:

codescalpel regenerate-manifest --signed-by "dev@example.com"

Common Patterns¶

JSON output for scripting¶

codescalpel analyze src/ --json | jq '.functions[] | .name'

Chain tools in a workflow¶

codescalpel extract-code src/api.py --function handler -o extracted.py
codescalpel analyze extracted.py --json
codescalpel generate-unit-tests extracted.py

CI/CD security gate¶

codescalpel verify-policy-integrity || exit 1
codescalpel scan src/ --json > scan.json
codescalpel code-policy-check src/ --strict || exit 1

Pre-refactor blast radius check¶

codescalpel get-symbol-references MyClass --json > refs.json
codescalpel simulate-refactor src/core.py --changes "rename MyClass to CoreService"
codescalpel get-call-graph src/core.py --format mermaid -o before.md

Getting Help¶

codescalpel --help                    # List all commands
codescalpel <command> --help          # Help for a specific command
codescalpel capabilities              # Show tier capabilities
codescalpel capabilities --tool extract_code   # Tool-specific limits

Docs: codescalpel.dev/docs
GitHub Issues: github.com/3D-Tech-Solutions/code-scalpel/issues
Pricing: codescalpel.dev/pricing

CLI Reference¶

Quick Start¶

Analysis Tools¶

analyze¶

get-file-context¶

get-call-graph¶

get-symbol-references¶

get-graph-neighborhood¶

get-project-map¶

get-cross-file-dependencies¶

crawl-project¶

Extraction Tools¶

extract-code¶

update-symbol¶

rename-symbol¶

Security Tools¶

scan¶

cross-file-security-scan¶

type-evaporation-scan¶

unified-sink-detect¶

scan-dependencies¶

Refactoring & Testing¶

simulate-refactor¶

generate-unit-tests¶

symbolic-execute¶

Policy & Governance¶

validate-paths¶

code-policy-check¶

verify-policy-integrity¶

Configuration Management¶

init¶

check¶

verify-policies¶

regenerate-manifest¶

Common Patterns¶

JSON output for scripting¶

Chain tools in a workflow¶

CI/CD security gate¶

Pre-refactor blast radius check¶

Getting Help¶

`analyze`¶

`get-file-context`¶

`get-call-graph`¶

`get-symbol-references`¶

`get-graph-neighborhood`¶

`get-project-map`¶

`get-cross-file-dependencies`¶

`crawl-project`¶

`extract-code`¶

`update-symbol`¶

`rename-symbol`¶

`scan`¶

`cross-file-security-scan`¶

`type-evaporation-scan`¶

`unified-sink-detect`¶

`scan-dependencies`¶

`simulate-refactor`¶

`generate-unit-tests`¶

`symbolic-execute`¶

`validate-paths`¶

`code-policy-check`¶

`verify-policy-integrity`¶

`init`¶

`check`¶

`verify-policies`¶

`regenerate-manifest`¶