Skip to main content

Getting Started

This guide covers the fastest path from installation to a useful local scan. Skylos works as a local CLI first; cloud upload, LLM review, and CI gates are optional layers you can add later.

Prerequisites​

Before installing Skylos, ensure your environment meets the following requirements:

  • Operating System: macOS, Linux, or Windows (WSL2 recommended).
  • Python: Version 3.10 or newer.
  • Package Manager: pip or uv.
note

Browser Support: Skylos is a CLI tool and does not require a web browser, although it can generate HTML reports that support Chrome, Edge, Firefox, and Safari.

Step 1: Installation​

Skylos is distributed via PyPI. Install it globally or within your project's virtual environment.

pip install skylos

To verify the installation, run:

skylos --version

Step 2: Run Your First Scan​

Go to the repository root and scan it:

skylos .

This starts with dead code detection. To run the main local audit, including dead code, dangerous flows, secrets, quality, and dependency checks:

skylos . -a

Optional: Initialize Project Config​

You do not need config for a first scan. Initialize Skylos when you want repository-owned thresholds, excludes, or gate policy.

  1. Navigate to your project folder.
  2. Run the initialization command:
skylos init

This will create (or append to) a pyproject.toml file with default settings:

[tool.skylos]
complexity = 10
nesting = 3
max_args = 5

Optional: Configure AI Access​

Skylos does not require an LLM for core static analysis. Configure a provider only if you want agent review or remediation workflows.

Skylos checks for keys in the following priority:

  1. Environment Variables: OPENAI_API_KEY or ANTHROPIC_API_KEY.
  2. System Keyring: Keys saved via previous interactive sessions.
  3. Interactive Prompt: You will be prompted to paste a key if none is found.
export OPENAI_API_KEY="sk-..."

Step 3: Review Results​

The CLI outputs findings as tables, grouped by category. Each table includes a legend explaining what the columns mean.

  • Dead Code (default): Unused functions, imports, classes, and variables. Each finding has a Conf (confidence) score — higher means safer to remove.
  • Security (--danger): Vulnerabilities like SQL injection and command injection. Shows Issue, Severity, and the Symbol (function) where it occurs.
  • Secrets (--secrets): Hardcoded credentials. Shows the Provider (e.g. AWS, Stripe) and a masked Preview.
  • Quality (--quality): Complexity, nesting, duplicate literals, and structural issues. Shows the measured value vs. the configured threshold (e.g. Complexity: 18 (max 10)).
  • AI Defects (--ai-defects): Evidence-backed AI-code failure modes such as phantom references, hallucinated APIs, impossible dependency versions, and weakened assertions. JSON uses the ai_defects bucket and finding category ai_defect; some rules keep historical SKY-L or SKY-D IDs for compatibility, while new AI-defect-only rules use SKY-A.
  • SCA (--sca): Known vulnerabilities in your dependencies. Shows the Package, Reachability, and the Fix version.

Reducing False Positives​

If Skylos flags code you know is used (common with visitor patterns or dynamic dispatch), enable tracing:

skylos . --trace

This runs your test suite and records which functions were actually called, eliminating false positives from dynamic code.

See Smart Tracing for details.

Step 4: Add CI Or Cloud Later​

Generate a GitHub Actions workflow:

skylos cicd init

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

Optional: Connect to Cloud​

Upload your scan results to the Skylos Cloud dashboard for history tracking, team collaboration, and trend visualization.

skylos . --upload

On first run, the browser opens automatically — sign in with GitHub, pick a project, and you're done. No API keys to copy or config files to edit.

tip

Every new account gets 50 starter credits and a 7-day Pro trial — no credit card required.

See Authentication for CI/CD setup, OIDC, and advanced options.