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 (deprecated)

Start the deprecated local web dashboard.

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

This command is deprecated and will be removed in a future major release. Use skylos . -a or skylos suite . for local analysis.

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 --ai-defects

skylos verify

Verify a changed file, range, or stdin code blob for AI-code trust findings. Add --contract .skylos/ai-contract.yml to enforce repo-specific generated-code truth such as required route decorators or approved phantom-symbol checks. This is the narrow in-loop verifier designed for coding agents and editor hooks, so it returns only AI-specific findings instead of the full dead-code/security report. In full scan JSON, AI-defect checks are grouped under ai_defects rather than quality or danger.

# Verify one file
skylos verify src/app.py

# Verify only the edited range
skylos verify src/app.py --range 40:75

# Scan the project for context, then return findings for one file
skylos verify . --file src/app.py --range 40:75 --project-context

# Let an editor or agent send an unsaved buffer
printf '{"file":"src/app.py","code":"def handler(): pass\n","range":"1:1"}' \
  | skylos verify . --stdin --no-fail

The command prints versioned JSON with tool: "verify_change", a status, the target file/range, and findings shaped for agent consumption:

{
  "schema_version": 1,
  "tool": "verify_change",
  "status": "fail",
  "findings": [
    {
      "rule_id": "SKY-D224",
      "vibe_category": "api_signature_hallucination",
      "ai_likelihood": "high",
      "range": {
        "file": "src/app.py",
        "start_line": 42,
        "start_col": 0,
        "end_line": 42,
        "end_col": 0
      },
      "message": "Call uses an API shape that is not present in the installed package.",
      "suggested_fix": "Update the call to match the installed package API surface.",
      "confidence": 80,
      "severity": "HIGH",
      "category": "ai_defect"
    }
  ]
}

Flag	Description
--file <path>	Target file when the positional path is a project root
--range L1:L2	Return findings that overlap a changed line range
--stdin	Read a JSON manifest with file, code, and optional range
--project-context	Scan the project path and filter to --file
--dependency-hallucinations	Include package metadata checks for hallucinated dependencies and versions
--exclude-folder <folder>	Add an excluded folder. Can be repeated
--confidence, -c	Analyzer confidence threshold. Default: 60
--no-fail	Exit 0 even when verify findings are returned
--output, -o <file>	Write JSON output to a file

Without --no-fail, skylos verify exits 1 when the JSON status is fail.

skylos debt <path>

Analyze technical debt hotspots for the specified path.

skylos debt .
skylos debt . --changed
skylos debt . --baseline
skylos debt . --show-history

Use this command when you want a debt hotspot report instead of the normal dead-code/security/quality output.

Flag	Description
--json	Output machine-readable debt results
--output, -o <file>	Write the debt report to a file
--top <n>	Limit the table output to the top N hotspots
--changed	Show only hotspots in git-changed files while keeping the debt score project-scoped
--baseline	Compare current hotspots against the saved debt baseline
--save-baseline	Save the current project debt snapshot as the debt baseline
--history	Append the current project debt summary to the debt history log
--show-history	Show saved debt history without running a new scan
--history-limit <n>	Limit saved history output to the latest N entries
--policy <file>	Use a specific skylos-debt.yaml policy file
--min-score <n>	Exit 1 if the repo debt score falls below the threshold
--fail-on-status <status>	Exit 1 if hotspots with a given baseline status exist
--with-agent	Use an LLM to summarize the top static debt hotspots
--agent-top <n>	Limit how many hotspots are summarized by the agent
--exclude <dir ...>	Exclude additional folders

For the full scoring model and baseline semantics, see Technical Debt.

Output Options

Flag	Description
--json	Output raw JSON to stdout
--llm	Output LLM-optimized report with code context for AI agents (Claude Code, Codex, etc.)
--format FORMAT	Select rich, json, llm, github, or concise output. concise prints only IDE-clickable file:line findings.
--output, -o <file>	Write results to a file
--tree	Display findings in a hierarchical tree format
--table	(Deprecated) Display findings in table format

Concise IDE-Friendly Output

Use concise output when you want terminal, editor, or test-script output without the banner, tables, progress text, CI tips, or Cloud CTA:

skylos --format concise src/test.py

src/test.py:1  unused function
src/test.py:5  unused class

Clean scans print nothing and exit 0. Scans with findings exit 1 unless --force is used.

Analysis Flags

Flag	Description
--danger	Enable security vulnerability scanning
--secrets	Enable API key and secret detection
--quality	Enable code quality checks (complexity, nesting, etc.)
--ai-defects	Enable evidence-backed AI defect checks such as phantom references, hallucinated APIs, impossible dependency versions, weakened test assertions, test-impact gaps, CI privilege expansion, and CLI surface drift
--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

Reference Graph Cache

Skylos has a persistent reference graph cache format at:

.skylos/index/v1/reference_graph.json

The cache stores file signatures, definitions, references, imports, and reverse dependencies keyed by content hash. Index-aware verifier and agent paths can reuse unchanged graph entries and conservatively invalidate changed files plus their direct dependents.

You should normally gitignore .skylos/index/. It is safe to delete; Skylos will rebuild cache payloads when an index-aware path writes them again. The cache does not index symlinks, non-regular files, or very large source files.

Diff Filtering

Flag	Description
--diff [BASE_REF]	Only report findings in lines changed since BASE_REF (e.g. --diff origin/main). Use --diff without a value to auto-detect (GITHUB_BASE_REF or origin/main). Unlike --diff-base which filters at the file level, --diff uses unified diff hunk headers for exact line-range matching.
--diff-base <ref>	(File-level) Only report findings in files changed since the given ref.

Example:

# Only show findings in lines your PR touched
skylos . --diff origin/main --danger --quality --ai-defects

# Auto-detect base ref (uses GITHUB_BASE_REF or defaults to origin/main)
skylos . --diff --danger --secrets --quality --ai-defects

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.

Deterministic Cleanup

Use skylos clean when you want a repeatable cleanup plan that can be reviewed before files are edited.

# Preview safe import/function cleanup edits without writing files
skylos clean . --dry-run --types import,function --confidence 80

# Apply the same kind of cleanup without prompting
skylos clean . --apply --types imports --confidence 80

# Comment out matches instead of removing them
skylos clean . --apply --comment-out --types import,function --confidence 80

Flag	Description
--dry-run	Print planned edits and write nothing
--apply	Apply matching cleanup edits without prompting
--confidence <N>	Minimum finding confidence; defaults to 80 in noninteractive mode
--types <list>	Comma-separated cleanup types; currently import and function
--comment-out	Comment out matches instead of deleting them

skylos clean still uses Skylos' CST codemods and path-containment checks. Automatic cleanup currently edits unused imports and unused functions only; classes, variables, and lower-confidence findings remain review items.

AI-Powered Features

Feature	Command	Description
AI-Powered Analysis	skylos agent scan . --model gpt-4.1	Hybrid static + LLM analysis with project context
AI Contract Setup	skylos contract init	Create .skylos/ai-contract.yml for repo-specific generated-code guardrails
In-Loop Verification	skylos verify . --file src/app.py --range 40:75	Fast, machine-readable AI-code trust verdict for changed code
AI Security Scan	skylos agent scan . --security	Security taskflow audit with repo map, file facts, and verifier-backed evidence
Automated Repair	skylos agent scan . --fix	Let the LLM fix what it found, re-scan to confirm closure, and attach proof-test metadata when available
PR Review	skylos agent scan --changed	Analyze only git-changed files
Local LLM	skylos agent scan . --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
--upload	false	Include --upload step to send scan results to the Skylos cloud dashboard. Requires SKYLOS_TOKEN in repo secrets.
--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 and metadata to Skylos Cloud. Uses SKYLOS_TOKEN, GitHub OIDC, or saved skylos login credentials. 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)

Cloud uploads are attributed by the resolved auth path. See Authentication and Enterprise Trust for the exact upload attribution and data-handling model.

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 --ai-defects --json -o report.json

Interactive cleanup:

skylos . -i --dry-run

Deterministic cleanup preview and apply:

skylos clean . --dry-run --types imports --confidence 80
skylos clean . --apply --types imports --confidence 80

CI/CD gate that blocks on critical issues:

skylos . --danger --quality --ai-defects --gate

AI-powered audit of changed files:

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

Whitelist a dynamic pattern:

skylos whitelist 'handle_*'
skylos whitelist --show