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-any: Enables all supported failure gates and exits with code 1 if any actionable finding is detected. For unused code, it uses zero tolerance unless --fail-threshold, config, or CYTOSCNPY_FAIL_THRESHOLD supplies a threshold.
  • --fail-on-quality: Causes the process to exit with code 1 if any code quality issues (like high complexity or deep nesting) are detected.
  • --fail-on-secrets: Enables secret scanning if needed and exits with code 1 if any secret findings are detected.
  • --fail-on-danger: Enables dangerous-code/taint scanning if needed and exits with code 1 if any danger or taint findings are detected.
  • --fail-on-missing-deps: Enables dependency analysis if needed and exits with code 1 if any missing dependency findings are detected.
  • --fail-on-unused-deps: Enables dependency analysis if needed and exits with code 1 if any unused dependency findings 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, project config from .cytoscnpy.toml or pyproject.toml is still honored, and explicit VS Code settings are passed as CLI flags that override matching thresholds.

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.
  • --deps: Analyze unused and missing dependencies by cross-referencing pyproject.toml / requirements.txt against imports found in the code. Opt-in — not run by default.

Analysis Configuration

  • --confidence <N>, -c: 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-folders <DIRS>: Exclude specific folders from analysis. Can be used multiple times.
  • --include-folders <DIRS>: 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.
  • --make-whitelist: Generates a Python whitelist from currently detected unused symbols.
  • --whitelist <PATH>: Loads one or more whitelist files to suppress matching dead-code findings.

CI/CD Failure Gates

These flags allow you to set strict gates for CI/CD. If any enabled gate fails, CytoScnPy exits with code 1. Failure gates that depend on optional scans enable those scans automatically.

  • --fail-on-any: Convenience gate for CI. Implies quality, secrets, danger/taint, missing dependency, and unused dependency failure gates. For unused code, it defaults to --fail-threshold 0.0 unless an explicit threshold is supplied.
  • --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.
  • --fail-on-quality: Exit with 1 if any quality issue is found.
  • --fail-on-secrets: Exit with 1 if any secret finding is found; implies --secrets.
  • --fail-on-danger: Exit with 1 if any danger or taint finding is found; implies --danger.
  • --fail-on-missing-deps: Exit with 1 if missing dependencies are found; implies --deps.
  • --fail-on-unused-deps: Exit with 1 if unused dependencies are found; implies --deps.

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-folders <DIRS>: Exclude specific folders from analysis.

files

Show per-file metrics table.

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

deps

Analyze dependency hygiene with CytoScnPy rule categories:

  • CSP-R001: imported package is missing from direct dependency declarations.
  • CSP-R002: declared production dependency is unused.
  • CSP-R003: imported package is present only as a transitive lockfile dependency.
  • CSP-R004: production code imports a development dependency.
  • CSP-R005: declared dependency belongs to the Python standard library.
cytoscnpy deps [OPTIONS] [PATHS]...
  • --json: Output JSON.
  • --requirements <FILE>: Path to a specific requirements file (default: auto-discover requirements.txt / requirements-dev.txt).
  • --ignore-unused <PKGS>: Comma-separated package names to suppress from the unused report.
  • --ignore-missing <PKGS>: Comma-separated import names to suppress from the missing report.
  • --exclude <DIRS>: Folders to exclude from import scanning.
  • --extra-installed: Also report packages installed in the venv but not declared.
  • --orphans: Report orphan packages — installed, undeclared, not imported, and not required by any other installed package.
  • --include-dev-unused: Include development dependencies in CSP-R002 findings. By default, dev dependencies from dependency groups, optional dependency groups, or dev/test requirements exports are not reported as unused.
  • --fail-on-any: Exit with code 1 if any dependency finding is found; also enables the extra-installed and orphan reports.
  • --fail-on-unused: Exit with code 1 if unused dependencies are found.
  • --fail-on-missing: Exit with code 1 if missing dependencies are found.
  • --fail-on-extra-installed: Exit with code 1 if extra installed packages are found; also enables the extra-installed report.
  • --fail-on-orphans: Exit with code 1 if orphan packages are found; also enables the orphan report.
  • --impact <PKG>: Show which transitive packages would be removable if <PKG> were dropped (requires a lockfile).
  • --venv <PATH>: Override the venv path (default: auto-detect .venv).
  • --lockfile <PATH>: Override the lockfile path (default: auto-detect uv.lock / poetry.lock).
  • -O, --output-file <FILE>: Save output to file.

Note: Use the deps subcommand when you want dependency analysis in isolation or need the extra flags (--extra-installed, --orphans, --impact). To include dependency findings alongside the main scan, pass --deps to the default analysis command.

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
project_type = "library"   # "library" (default) or "application"
# 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"]

# Rule suppression
ignore = ["CSP-P003"]      # Globally ignore specific rule IDs
per-file-ignores = { "tests/*" = ["CSP-D701"], "**/__init__.py" = ["CSP-L001"] }
# Glob behavior: "*" matches a single path segment, "**" matches recursively.

# Clone detection
clones = false             # Enable duplicate code detection
clone_similarity = 0.8     # Similarity threshold (0.0-1.0)

# CI/CD
fail_threshold = 5.0
fail_on_secrets = true
fail_on_danger = true

# Inline whitelist (suppress specific dead-code symbols)
[[cytoscnpy.whitelist]]
name = "my_handler"
pattern = "exact"          # "exact" (default), "wildcard", or "regex"
# file = "src/api/*.py"    # Optional: restrict to a specific file glob

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

Dependency Analysis

[cytoscnpy.deps]
enabled = true                        # Run dep analysis by default (same as --deps)
ignore_unused = ["celery", "redis"]   # Suppress specific unused-dep findings
ignore_missing = ["numpy"]            # Suppress specific missing-dep findings
fail_on_unused = true                 # Fail if unused dependencies are reported
fail_on_missing = true                # Fail if missing dependencies are reported
fail_on_extra_installed = false       # Fail on undeclared installed packages
fail_on_orphans = false               # Fail on installed orphan packages

# Custom package → import name mappings (for packages where the import name
# differs from the package name and is not in the built-in mapping)
[cytoscnpy.deps.package_mapping]
"my-internal-lib" = ["mylib", "mylib_ext"]

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"]
custom_sanitizers = ["mylib.clean"] # Functions that clear taint

Exit Codes

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

See Also