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.
Credits
skylos credits
Check your credit balance, plan, and recent transactions.
skylos credits
Output:
[My Org] (pro plan)
Balance: 1,500 credits
Recent activity:
+10000 Purchased 10000 credits (team pack)
-1 Scan upload
-10 AI code remediation
Buy credits: https://skylos.dev/dashboard/billing
Requires skylos login first. See Billing & Credits for pricing.
CI/CD Commands
skylos cicd init
Generate a GitHub Actions workflow file for automated scanning.
skylos cicd init
| Flag | Default | Description |
|---|---|---|
--python-version | 3.12 | Python version for the workflow |
--triggers | pull_request push | GitHub event triggers |
--analysis | dead-code security quality secrets | Analysis types to enable |
--no-baseline | false | Skip baseline comparison |
--llm | false | Include LLM-enhanced analysis |
--model | — | LLM model to use with --llm |
--output, -o | .github/workflows/skylos.yml | Output file path |
skylos cicd gate
Run the quality gate (exit code 0 = pass, 1 = fail). Use in CI to block merges.
skylos cicd gate --input skylos-report.json
| Flag | Description |
|---|---|
--input, -i | Read results from a JSON report file |
--strict | Fail on any issues found |
--summary | Write markdown summary to $GITHUB_STEP_SUMMARY |
skylos cicd annotate
Emit GitHub Actions annotations (inline warnings/errors on PR diffs).
skylos cicd annotate --input skylos-report.json
| Flag | Description |
|---|---|
--input, -i | JSON report file |
--max | Maximum annotations (default: 50) |
--severity | Filter by severity: critical, high, medium, low |
skylos cicd review
Post inline review comments on a pull request via the gh CLI.
skylos cicd review --input skylos-report.json --pr 42
| Flag | Description |
|---|---|
--input, -i | JSON report file |
--pr | PR number (auto-detected in CI) |
--repo | owner/repo (auto-detected in CI) |
--summary-only | Post only a summary comment, no inline comments |
--max-comments | Maximum inline comments (default: 25) |
--diff-base | Base branch for diff (default: origin/main) |
Cloud & CI Flags
| Flag | Description |
|---|---|
--upload | Upload scan results to Skylos Cloud (requires skylos login first). Costs 1 credit. |
--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_FunctionDefcalled viagetattr) - Plugin hooks (
pytest_configure,pytest_addoption) - Dynamic dispatch (
getattr(obj, method_name)())
skylos . --trace
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:
- Environment variables (
OPENAI_API_KEYorANTHROPIC_API_KEY) - System keyring (saved from previous sessions)
- 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