CLI Reference

Basic Usage

skylos <path> [options]

The <path> argument can be a directory (scans recursively) or a single file.

Commands

skylos init

Initialize Skylos configuration in the current directory.

skylos init

Creates or appends a [tool.skylos] section to pyproject.toml with default settings.

skylos run

Start the local analysis server with a web UI.

skylos run [--exclude-folder <folder>] [--include-folder <folder>] [--no-default-excludes]

Launches a Flask server at http://localhost:5000 for interactive analysis. Requires flask and flask-cors.

skylos whitelist

Manage the whitelist for suppressing false positives.

# Add a glob pattern
skylos whitelist 'handle_*'

# Add with reason (recommended for teams)
skylos whitelist my_func --reason "Called via registry lookup"

# View current whitelist
skylos whitelist --show

Flag	Description
--reason, -r	Add reason/documentation for the whitelist entry
--show, -s	Display all current whitelist entries

Patterns are saved to [tool.skylos.whitelist] in pyproject.toml.

skylos <path>

Run static analysis on the specified path.

skylos . --danger --quality

Output Options

Flag	Description
--json	Output raw JSON to stdout
--output, -o <file>	Write results to a file
--tree	Display findings in a hierarchical tree format
--table	(Deprecated) Display findings in table format

Analysis Flags

Flag	Description
--danger	Enable security vulnerability scanning
--secrets	Enable API key and secret detection
--quality	Enable code quality checks (complexity, nesting, etc.)
--trace	Run tests with call tracing to capture dynamic dispatch (visitor patterns, getattr, plugins)
--confidence	Confidence threshold (0-100). Lower values include more uncertain findings. Default: 60

Folder Exclusion

Flag	Description
--exclude-folder <folder>	Exclude a folder from analysis. Can be used multiple times.
--include-folder <folder>	Force include a folder that would otherwise be excluded.
--no-default-excludes	Do not exclude default folders (__pycache__, .git, venv, etc.)
--list-default-excludes	Print the default excluded folders and exit

Example:

# Exclude tests and migrations, but include venv
skylos . --exclude-folder tests --exclude-folder migrations --include-folder venv

Interactive Mode

Flag	Description
--interactive, -i	Interactively select which findings to act on
--dry-run	Show what would be removed without making changes
--comment-out	Comment out dead code instead of deleting it

Interactive mode requires the inquirer package.

AI-Powered Features

Feature	Command	Description
AI-Powered Analysis	skylos agent analyze . --model gpt-4.1	Hybrid static + LLM analysis with project context
AI Audit	skylos agent security-audit .	Deep LLM review with interactive file selection
Automated Repair	skylos agent analyze . --fix	Let the LLM fix what it found
PR Review	skylos agent review	Analyze only git-changed files
Local LLM	skylos agent analyze . --base-url http://localhost:11434/v1 --model codellama	Use Ollama/LM Studio (no API key needed)

You can use the --model flag to specify the model that you want. We support Gemini, Groq, Anthropic, ChatGPT and Mistral.

Cloud & CI Flags

Flag	Description
--upload	Upload scan results to Skylos Cloud (requires skylos sync connect first)
--strict	Exit with code 1 if quality gate fails (use in CI to block merges)
--force, -f	Bypass quality gate locally (still uploads if --upload is set)

Runtime Analysis

Flag	Description
--trace	Run pytest with sys.settrace() to record all function calls, reducing false positives from dynamic code

When to Use --trace

Use --trace when static analysis flags code you know is used:

• Visitor patterns (visit_FunctionDef called via getattr)
• Plugin hooks (pytest_configure, pytest_addoption)
• Dynamic dispatch (getattr(obj, method_name)())

skylos . --trace

note

The .skylos_trace file is saved in your project root. Commit it to skip re-running tests on subsequent scans.

Quality Gate

skylos <path> --gate [command...]

Flag	Description
--gate	Run as a quality gate. Blocks if thresholds are exceeded.

If the gate passes, Skylos either runs the provided command or launches the deployment wizard. If the gate fails, it shows reasons and (unless strict = true) offers a bypass prompt.

Example:

skylos . --danger --gate

Other Options

Flag	Description
--version	Print version and exit
--verbose, -v	Enable verbose logging

Exit Codes

Code	Meaning
0	Success (no issues or gate passed)
1	Failure (analysis error or gate failed)

AI-Powered Features (Deprecated)

Flag	Description
--fix	Use AI to automatically fix detected issues
--audit	Deep scan files using AI for logic and security review

These features require an API key. Skylos checks:

1. Environment variables (OPENAI_API_KEY or ANTHROPIC_API_KEY)
2. System keyring (saved from previous sessions)
3. Interactive prompt (if neither is found)

Examples

Basic dead code scan:

skylos .

Full analysis with JSON output:

skylos . --danger --secrets --quality --json -o report.json

Interactive cleanup:

skylos . -i --dry-run

CI/CD gate that blocks on critical issues:

skylos . --danger --quality --gate

AI-powered audit of changed files:

skylos . --audit --model claude-sonnet-4-20250514

Whitelist a dynamic pattern:

skylos whitelist 'handle_*'
skylos whitelist --show