Skip to content

CLI Reference

This document provides a comprehensive reference for the cytoscnpy command-line interface.

Command Syntax

cytoscnpy [OPTIONS] [COMMAND]

Main Options

Input & Output

  • [paths]: One or more paths to analyze (files or directories). If omitted, CytoScnPy defaults to the current working directory.
  • --root <PATH>: Explicitly sets the project root. This is highly recommended for CI/CD environments to ensure that path-based security containment is correctly applied and that relative imports are resolved consistently. When --root is used, positional [paths] are not allowed. It also ensures that reports (SARIF, GitLab, etc.) use paths relative to this root.
  • --format <FORMAT>: Specifies the output format. Supported values: text (default), json, junit, github, gitlab, markdown, sarif, grouped (deprecated).
  • --json: Format the result as a raw JSON object. Shorthand for --format json. This is ideal for piping into tools like jq or for consumption by CI/CD scripts.
  • --verbose, -v: Prints detailed logs during the analysis process, including which files are being scanned and any non-fatal issues encountered.
  • --quiet: Minimalist output. Only the final summary table (or JSON) is displayed, suppressing the per-file findings table.
  • --fail-on-quality: Causes the process to exit with code 1 if any code quality issues (like high complexity or deep nesting) are detected.
  • --html: Generates a self-contained, interactive HTML report. Note that this feature may require additional dependencies and automatically enables quality scanning.
  • --client <CLIENT>: Identify the calling editor/client. Currently only vscode is supported. When vscode is set, scan enable/disable comes only from CLI flags (VS Code settings), but project config is still loaded for advanced tuning (for example, custom secret patterns).

Scan Types

  • --secrets, -s: Actively scans for high-entropy strings, API keys, and hardcoded credentials. It checks variables, strings, and even comments (depending on configuration).
  • --danger, -d: Enables security scanning for dangerous patterns like eval(), exec(), and insecure temporary file creation. It also activates taint analysis to track user-controlled data flowing into dangerous sinks (e.g., SQL injection or command injection points). See Dangerous Code for a full rule list.
  • --quality, -q: Runs code quality checks including Cyclomatic Complexity, Maintainability Index, block nesting depth, and function length/argument counts.
  • --no-dead, -n: Skips the default dead code detection. Use this if you only care about security vulnerabilities or quality metrics and want to speed up the analysis.

Analysis Configuration

  • --confidence <N>: Sets a minimum confidence threshold (0-100). CytoScnPy uses a scoring system for dead code; setting this to 80, for example, will suppress "noisy" findings where the tool isn't certain the code is unused.
  • --exclude-folder <DIR>: Exclude specific folders from analysis. Can be used multiple times.
  • --include-folder <DIR>: Force-include specific folders in analysis. Can be used multiple times.
  • --include-tests: By default, CytoScnPy ignores files in folders like tests/ or test/ starting from version 1.2.2. Use this flag to include them in the analysis.
  • --include-ipynb: Enables scanning of Jupyter Notebook files. CytoScnPy extracts the Python code from cells and analyzes it as a virtual module.
  • --ipynb-cells: When combined with --include-ipynb, this reports findings with cell numbers instead of just line numbers, making it easier to locate issues in the Notebook UI.
  • --clones: Activates duplicate code detection. It uses AST-based hashing to find code blocks that are identical or nearly identical across your codebase.
  • --clone-similarity <N>: Sets the similarity threshold for clone detection (0.0 to 1.0). A value of 1.0 finds only exact duplicates; a lower value like 0.8 (default) finds similar logic that might be refactored.
  • --fix: Enables "Dead Code Auto-Fix" mode. By default, this is a dry-run—it will show you exactly what code would be removed without touching your files.
  • --apply, -a: Executes the changes suggested by --fix. Warning: This modifies your source code. It is highly recommended to run with --fix first to review changes, and to have a clean Git state before applying.
  • --fix targets: functions, methods, classes, imports, and unused variables.
  • --fix always enforces a minimum confidence floor of 80% for safety, even if --confidence is set lower.
  • In dry-run mode with --json, CytoScnPy emits a deterministic JSON fix plan (kind: "dead_code_fix_plan") suitable for editor/CI consumption.
  • When removing the only method in a class, CytoScnPy inserts pass to keep valid Python syntax.

Quality Thresholds (Gate Overrides)

These flags allow you to set strict "gates" for your code. If any part of the codebase exceeds these numbers, CytoScnPy will exit with code 1.

  • --fail-threshold <N>: Exit with 1 if the total percentage of unused code exceeds N.
  • --max-complexity <N>: Sets the maximum allowed Cyclomatic Complexity (standard is often 10).
  • --min-mi <N>: Sets the minimum allowed Maintainability Index (usually 40-65).
  • --max-nesting <N>: Sets the maximum allowed indentation/nesting level (e.g., 3 or 4).
  • --max-args <N>: Sets the maximum number of arguments a function can have.
  • --max-lines <N>: Sets the maximum number of lines a function can have.

Subcommands

raw

Calculate raw metrics (LOC, LLOC, SLOC, Comments, Multi, Blank).

cytoscnpy raw [OPTIONS] <PATH>
  • -j, --json: Output JSON.
  • -s, --summary: Show summary metrics.
  • -O, --output-file <FILE>: Save output to file.
  • -e, --exclude <DIR>: Folders to exclude.
  • -i, --ignore <PATTERN>: Glob patterns to ignore.

cc

Calculate Cyclomatic Complexity.

cytoscnpy cc [OPTIONS] <PATH>
  • -a, --average: Show average complexity.
  • --total-average: Show total average complexity.
  • -s, --show-complexity: Show complexity score with rank.
  • -n, --min <RANK>: Set minimum complexity rank (A-F).
  • -x, --max <RANK>: Set maximum complexity rank (A-F).
  • -o, --order <ORDER>: Ordering function (score, lines, alpha).
  • --no-assert: Do not count assert statements.
  • --xml: Output XML.
  • --fail-threshold <N>: Exit 1 if any block has complexity > N.
  • -j, --json: Output JSON.
  • -e, --exclude <DIR>: Folders to exclude.
  • -i, --ignore <PATTERN>: Glob patterns to ignore.
  • -O, --output-file <FILE>: Save output to file.

hal

Calculate Halstead Metrics.

cytoscnpy hal [OPTIONS] <PATH>
  • -f, --functions: Compute metrics on function level.
  • -j, --json: Output JSON.
  • -e, --exclude <DIR>: Folders to exclude.
  • -i, --ignore <PATTERN>: Glob patterns to ignore.
  • -O, --output-file <FILE>: Save output to file.

mi

Calculate Maintainability Index.

cytoscnpy mi [OPTIONS] <PATH>
  • -s, --show: Show actual MI value.
  • -a, --average: Show average MI.
  • -n, --min <RANK>: Set minimum MI rank (A-C).
  • -x, --max <RANK>: Set maximum MI rank (A-C).
  • --multi: Count multiline strings as comments (default: true).
  • --fail-threshold <N>: Exit 1 if any file has MI < N.
  • -j, --json: Output JSON.
  • -e, --exclude <DIR>: Folders to exclude.
  • -i, --ignore <PATTERN>: Glob patterns to ignore.
  • -O, --output-file <FILE>: Save output to file.

stats

Generate comprehensive project statistics report.

cytoscnpy stats [OPTIONS] <PATH>
  • -a, --all: Enable all analysis: secrets, danger, quality, files.
  • --root <PATH>: Project root for analysis (use instead of positional path).
  • -s, --secrets: Scan for secrets.
  • -d, --danger: Scan for dangerous code.
  • -q, --quality: Scan for quality issues.
  • -j, --json: Output JSON.
  • -o, --output <FILE>: Output file path.
  • --exclude-folder <DIR>: Exclude specific folders from analysis.

files

Show per-file metrics table.

cytoscnpy files [OPTIONS] <PATH>
  • -j, --json: Output only JSON.
  • --exclude-folder <DIR>: Exclude specific folders from analysis.

mcp-server

Start MCP server for LLM integration.

cytoscnpy mcp-server

Note: The mcp-server subcommand is handled by the cytoscnpy-cli binary. If you installed the Python package, cytoscnpy mcp-server will print an error. Use the standalone CLI build for MCP.

init

Initialize CytoScnPy configuration in the current directory.

cytoscnpy init

This creates .cytoscnpy.toml (or appends [tool.cytoscnpy] to pyproject.toml) and adds .cytoscnpy to .gitignore when possible.

Configuration File

Create .cytoscnpy.toml in your project root to set defaults.

[cytoscnpy]
# Core settings
confidence = 60
secrets = true
danger = true
quality = true
include_tests = false
include_ipynb = false
# Note: ipynb_cells is currently a CLI-only option

# Quality thresholds
max_complexity = 10        # Max cyclomatic complexity
max_nesting = 3            # Max nesting depth
max_args = 5               # Max function arguments
max_lines = 50             # Max function lines
min_mi = 40.0              # Min Maintainability Index

# Path filters
exclude_folders = ["build", "dist", ".venv"]
include_folders = ["src"]

# CI/CD
fail_threshold = 5.0

Advanced Configuration

Secret Scanning

[cytoscnpy.secrets_config]
entropy_threshold = 4.5
min_length = 16
entropy_enabled = true
scan_comments = true
skip_docstrings = false
min_score = 50
suspicious_names = ["db_password", "oauth_token"]

[[cytoscnpy.secrets_config.patterns]]
name = "Slack Token"
regex = "xox[baprs]-([0-9a-zA-Z]{10,48})"
severity = "HIGH"
rule_id = "CSP-SCUSTOM-001" # Optional

Dangerous Code + Taint Analysis

[cytoscnpy.danger_config]
enable_taint = true
severity_threshold = "LOW" # LOW, MEDIUM, HIGH, CRITICAL
excluded_rules = ["CSP-D101"]
custom_sources = ["mylib.get_input"]
custom_sinks = ["mylib.exec"]

Exit Codes

  • 0: Success, no issues found (or issues below threshold).
  • 1: Issues found exceeding thresholds (quality, security, or fail_threshold).
  • 2: Runtime error or invalid arguments.

See Also