Skip to main content

Getting Started

This guide covers the setup process for using Skylos on a local machine.

Prerequisites​

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

  • Operating System: macOS, Linux, or Windows (WSL2 recommended).
  • Python: Version 3.9, 3.10, 3.11, or 3.12.
  • 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: Initialize a Project​

To scan a repository, you must initialize Skylos in the project root. This creates the configuration file required to define your quality policies.

  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

Step 3: Configure AI Access (Optional)​

Skylos does not require a proprietary token. However, to use Auto-Fix (--fix) or Audit (--audit) features, you must provide an API key for a supported LLM provider.

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 4: Run Your First Scan​

Once installed and initialized, you can perform a static analysis scan.

skylos .

Reviewing 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)).
  • SCA (--sca): Known vulnerabilities in your dependencies. Shows the Package, Reachability, and the Fix version.

To enable all scans at once:

skylos . -a

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 5: Connect to Cloud (Optional)​

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.