Quick Start

Skylos is an open-source static analysis tool and PR gate. Use it locally first, then add CI once the output makes sense for your repository.

The Three Commands

pip install skylos
skylos .            # find problems; your code and findings stay on your machine
skylos cloud        # optional: track results per branch on Skylos Cloud
skylos cicd init    # add a Skylos check to every pull request

• skylos . finds problems. Your code and findings stay on your machine.
• skylos cloud is optional. It tracks results per branch on Skylos Cloud.
• skylos cicd init adds a Skylos check to every pull request. See CI/CD Integration.

skylos . finds dead code. skylos . -a runs every check (security, secrets, quality, AI-code defects, dependencies) and still stays local, except that it looks up package names online: OSV.dev for known CVEs, and PyPI or npm for packages that don't exist.

The steps below go through each command in more detail.

1. Install

pip install skylos

Verify the CLI:

skylos --version

See Installation for uv, source installs, Docker, and optional extras.

Choose The Right Command

Choose by the thing you need Skylos to inspect:

Goal	Command	Input
Scan source code	skylos PATH	Repository source and configuration
See what a change touches before reviewing it	skylos done map --base main	Changed Python and TypeScript/JavaScript functions since the merge base
Verify source for AI-code defects	skylos verify [PATH]	Source; Python working changes also get a behavior comparison with Git HEAD
Check an exact local GPU release	skylos preflight [ARTIFACT]	Local built artifact and declared GPU fleet
Find container vulnerabilities	skylos image scan IMAGE@sha256:<digest> --platform os/arch	Remote registry image scanned by a separately installed Trivy
Run the combined repo report	skylos suite [DIRECTORY]	Static, debt, defense, and provenance checks
Check agent guardrails	skylos defend [DIRECTORY]	Python and TypeScript/JavaScript LLM and agent implementation source
Work through cleanup	skylos cleanup [PATH] --next	Prioritized tasks and local history; selected Python edits require explicit preview/apply options; see Cleanup
Remove Python dead code	skylos clean [PATH] --dry-run	Python import/function cleanup candidates; --dry-run never writes

verify scans source for AI-code defects; its separate Python behavior model compares working files with Git HEAD. preflight inspects a local built GPU artifact. A digest-pinned OCI reference provides identity only and returns UNKNOWN in the CLI. image scan finds container CVEs. Run skylos --help for this chooser and skylos commands for the installed command-family map.

For a focused cleanup workflow, start with a task and review its patch:

skylos cleanup . --next
skylos cleanup . --task TASK_ID
skylos cleanup . --task TASK_ID --apply --test-cmd "pytest -q test/test_orders.py"

Use an ID from the report and the relevant test command for your project. The default command leaves source unchanged and saves local history. Applying supports conservative Python unused-function, allowlisted unused-import and f-string conversion edits. Other tasks need manual changes. Tests run only with --test-cmd; a static rescan alone leaves an edit applied_unverified. See Cleanup for supported cases and verification limits.

2. Run Your First Scan

From the repository root:

skylos .

This starts with dead code detection. Skylos reports unused functions, classes, imports, variables, files, and framework entrypoint issues with confidence scores.

When the scan finds issues, it ends with what to run next:

Found 3 issues: security 2, quality 1.
Next: skylos cloud      track these per branch on Skylos Cloud (sends findings, not your repository)
      skylos cicd init  check every pull request in CI

3. Add Security, Secrets, And Quality

skylos . -a

The -a scan enables the main static checks:

Family	Examples
Dead code	unused functions, imports, classes, files, package entrypoints
Security	SQL injection, XSS, SSRF, path traversal, command injection, unsafe deserialization
Config	CI/CD workflow risk, Docker Compose edge runtime exposure, systemd edge service hardening
Secrets	API keys, tokens, private credentials, high-entropy strings
Quality	complexity, deep nesting, duplicate branches, long functions, inconsistent returns
AI-code defects	phantom references, hallucinated APIs, unfinished code, weakened assertions
Dependencies	supported manifest inventory and OSV vulnerability checks

For exact rules, see Rules Reference.

Most source analysis is local. The dependency/SCA family may query OSV. Use explicit analyzer flags instead of -a when an offline run must exclude that network-backed family.

4. Keep Findings Focused On Active Work

For pull requests and large legacy repositories, scan only changed lines:

skylos . -a --diff origin/main

For intentional dynamic code, use runtime tracing:

skylos . --trace

See Smart Tracing and Configuration for baselines, suppressions, and whitelists.

To review the change itself, list what it touches and what to read first:

skylos done map --base origin/main

See Change Map.

Optional: Track Results On Skylos Cloud

skylos cloud

skylos cloud runs every check (-a), shows the findings, uploads them to Skylos Cloud, then prints this branch's quality gate and one link to it. The first run opens your browser to log in and pick the project for this repo. It sends findings, not your repository.

See Cloud Platform for what it sends, what you see, and how to use it in CI.

5. Add A GitHub Actions PR Gate

Generate a workflow:

skylos cicd init

Commit it:

git add .github/workflows/skylos.yml
git commit -m "Add Skylos CI gate"
git push

On GitLab CI, Jenkins, Bitbucket Pipelines, Azure Pipelines or CircleCI, the same skylos cicd init sets up that CI's gate instead; see Other CI Providers.

See CI/CD Integration for local-only gates, cloud uploads, GitHub OIDC, tokens, annotations, and branch protection.

6. Optional Workflows

Goal	Command	Docs
Technical debt hotspots	skylos debt .	Technical Debt
AI-assisted review	skylos agent scan .	AI Features
Pre-deployment agent verification	skylos defend . --format md	Agent Verification
Built GPU artifact check	skylos preflight build/app	Release Reliability
Container vulnerability scan	skylos image scan IMAGE@sha256:<digest> --platform linux/amd64	CLI Reference
Runtime agent behavior test	skylos agent init && skylos agent test --allow-contract-endpoint	Agent Behavior Testing
Track results on Skylos Cloud	skylos cloud	Cloud Platform
MCP server for AI assistants	skylos mcp	MCP Server

image scan requires Trivy to be installed separately on PATH. It forces Trivy's remote image source, so the registry must be reachable and any required registry authentication must already be configured. Findings are report-only unless you add --fail-on LEVEL.

suite accepts a directory and may query OSV and public package registries. It returns 0 when the report contains findings; operational, output, upload, or Cloud gate failures are nonzero. defend also accepts a directory and is report-only unless --fail-on, --min-score, or a gate policy is set. clean supports Python import/function transforms; without a mode it is interactive and can write after confirmation. Use --dry-run for a guaranteed no-write preview. A completed apply pass can still exit 0 after printing an individual transform failure, so review its completion output.

Cheatsheet

I want to...	Command
Find dead code	skylos .
Run every main source analyzer	skylos . -a
Find security issues	skylos . --danger
Find hardcoded secrets	skylos . --secrets
Check code quality	skylos . --quality
Check AI defects	skylos . --ai-defects
Verify source for AI-code defects	skylos verify
Check a built GPU artifact	skylos preflight build/app
Scan a pinned image for CVEs	skylos image scan IMAGE@sha256:<digest> --platform linux/amd64
Run the combined repo report	skylos suite
Scan changed lines only	skylos . -a --diff origin/main
See what a change touches	skylos done map --base origin/main
Gate locally	skylos . -a --gate
Print concise IDE output	skylos --format concise src/test.py
Track results per branch on Skylos Cloud	skylos cloud
Set up a pull request gate for your CI	skylos cicd init
Export JSON	skylos . -a --json -o skylos-results.json

Getting Help

• CLI Reference
• FAQ
• GitHub Issues