CLI Reference

Basic Usage

skylos <path> [options]

This form scans source code. The <path> argument can be a directory (scanned recursively) or one file. A bare skylos or skylos --help opens the command chooser; skylos <path> --help shows source-scan flags.

Choose The Command By Its Input

Question	Command	Input Skylos reads
What problems are in this source tree?	skylos <path>	Source and project configuration; dead code by default, every main source analyzer with -a
What does this change touch, and what should I read first?	skylos done map --base main	Each changed Python or TypeScript/JavaScript function since the merge base, with its old and new code, callers and removed security checks, sorted into read first, read, skim and skip (skip only when the logic is proven the same)
What AI-code mistakes are in this source?	skylos verify [path]	The selected source target, plus a separate Git HEAD behavior comparison for supported Python working changes
Will this exact local GPU build fit the declared fleet?	skylos preflight [ARTIFACT]	A local built artifact plus .skylos/gpu-targets.yml or .yaml; OCI input is identity-only in the CLI
What vulnerabilities are in this container?	skylos image scan IMAGE@sha256:<digest> --platform os/arch	A remote registry image scanned through separately installed Trivy
What does the combined repo report contain?	skylos suite [DIRECTORY]	Static analysis, technical debt, AI defense, and provenance
Does an agent implementation have deployment guardrails?	skylos defend [DIRECTORY]	Recognized Python and TypeScript/JavaScript LLM integrations
What cleanup should I review next?	skylos cleanup [path] --next	Quality, AI-code and dead-code tasks, with local history and explicit preview/apply options; see Cleanup
Which Python dead code can Skylos remove?	skylos clean [path] --dry-run	Python import/function cleanup candidates; --dry-run never writes

The three similarly placed checks have different inputs: verify scans source and separately models supported Python working changes, preflight statically inspects a local built GPU artifact, and image scan asks Trivy to inspect a remote registry image. Optional paths default to the current directory; suite and defend require a directory. Run skylos commands for the installed command-family map.

Commands

Top-Level Command Map

This table maps the active top-level families. Run skylos commands for the installed family map and skylos <family> --help for its real parser options.

Command	Purpose
skylos setup [path]	Once per repository: Skylos steps in CLAUDE.md and AGENTS.md, Skylos tools for Claude Code (.mcp.json) and Codex, the PR check, and the code map
skylos open [path]	One local page: the code diagram, what changed and what it affects, every check run, and a Check this change button
skylos PATH [PATH ...]	Scan source; dead code by default, every main source analyzer with -a
skylos cloud [PATH]	Scan with every check, upload the findings (not your repository) and show this branch's gate and link
skylos suite [DIRECTORY]	Build one static, debt, defense, and provenance report
skylos verify [path]	Scan source for AI-code mistakes and separately model supported Python working changes
skylos preflight [ARTIFACT]	Check an exact local built GPU artifact against its fleet; OCI is UNKNOWN in the CLI
skylos done [map|receipt]	Run the tests and completion checks on a change, show the change map (map), or print the latest receipt (receipt)
skylos cleanup [path]	Review findings, organize local plans, preview supported edits, and explicitly apply and check a selected patch
skylos clean [path]	Preview or apply Python import/function cleanup
skylos review [path]	Record and manage local finding decisions
skylos baseline [path]	Save the current finding baseline
skylos debt [path]	Rank technical-debt hotspots and trends
skylos lint [RUFF_ARGS ...]	Forward arguments to ruff check
skylos sbom [path]	Export supported dependency inventory as CycloneDX JSON
skylos discover [path]	Inventory recognized Python and TypeScript/JavaScript LLM integrations and tools
skylos defend [DIRECTORY]	Report static guardrails; threshold flags or policy make it a gate
skylos image scan ...	Ask installed Trivy to scan a pinned remote image for vulnerabilities
skylos ingest <trivy|claude-security>	Normalize findings from an external tool
skylos compare [path] --against REPORT	Compare Skylos with an incumbent report
skylos provenance [path]	Detect AI-authored code in PR changes
skylos agent <command>	Run LLM review, Deep Mode, remediation, behavior tests, or agent-state workflows; install the agent hooks (install-hooks) and print hardened agent settings (harden, see Supply Chain)
skylos cicd <command>	Generate or run CI gates, annotations, and PR review output
skylos rules <command>	Initialize, validate, list, install, or remove rule packs
skylos contract <command>	Initialize, validate, or inspect AI hallucination contracts
skylos cache <clear|stats>	Clear or measure cached run data
skylos whitelist [pattern|--show]	Manage symbol whitelist patterns
skylos sonar import [properties_file]	Create a Skylos migration plan from Sonar properties
skylos init	Initialize project configuration
skylos doctor	Check installation and language-engine health
skylos badge	Print README badge Markdown
skylos login, whoami, project, sync	Manage the optional Cloud connection and project
skylos key, credits	Manage provider keys and view Cloud credits
skylos commands, tour	Show the command map or guided capability tour

skylos run and skylos city are removed compatibility names and exit 2 with replacement guidance.

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

skylos run exits with code 2. Use skylos . -a for the main source audit or skylos suite for the combined repository report.

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 cloud [PATH] [scan flags]

Scan PATH (default .) with every check (-a), show the findings, upload them to Skylos Cloud, then show the quality gate for this branch and one link to it.

skylos cloud                    # scan this repo and upload
skylos cloud --gate             # same, and exit 1 when the Cloud gate fails
skylos cloud --danger --secrets # run only these checks
skylos cloud src --exclude build

Topic	Behavior
Checks	Every check (-a), unless you name some, e.g. --danger --secrets
Sends	Findings with file paths and code snippets of up to 7 lines (none for secrets), the branch, the commit, the git author email of each flagged line, and a map of your functions and classes (names, files, lines, sizes, which calls which). Not your repository
First run	Opens your browser to log in and pick the project for this repo
Flags	The same scan flags as skylos <path>
Gate and exit code	Shows the Skylos Cloud quality gate: the project's policy in Skylos Cloud. Exit 0 even when it fails. Add --gate to exit 1 when it fails (use this in CI). skylos . --gate is a different, local gate: it uses [tool.skylos.gate] and uploads nothing
--no-upload	Refused with exit 2: skylos cloud always uploads. Run skylos . for a local-only scan
No terminal and no login	Stops before scanning and exits 1 with "Not connected to Skylos Cloud. Run skylos login in a terminal, or set SKYLOS_TOKEN to a project token (create one in your project's Settings on skylos.dev)." In GitHub Actions or GitLab CI it uses the CI identity (OIDC) or SKYLOS_TOKEN

skylos cloud --help prints this summary. --upload on a scan is the manual form of skylos cloud: it uploads exactly the checks you picked. See Cloud Platform for example output.

skylos verify [path]

Scan a file, directory, 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

For a directory target, the AI-defect analyzer scans that selected tree. Only the separate Python behavior result compares working-tree functions with Git HEAD; it does not narrow all analyzer findings to changed files. Path targets enable dependency hallucination checks by default and may query public package registries. Use --no-dependency-hallucinations to disable those lookups.

On a terminal, the command renders a human report. It emits versioned JSON with tool: "verify_change" when stdout is redirected, when --stdin is used, or to the file selected by --output. That result contains a status, target file/range, and findings shaped for agent consumption:

{
  "schema_version": 2,
  "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
--no-dependency-hallucinations	Disable dependency checks and package-registry lookups
--contract <path>	Apply a specific AI hallucination contract
--no-contract	Disable contract discovery and application
--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
--diff REF	Source build: verify changed lines since a Git baseline; an opted-in type check also compares diagnostic origins
--type-check	Unreleased: run the installed project checker with its real configuration
--type-checker auto|mypy|pyright|pyrefly|tsc	Unreleased: select the checker; requires --type-check
--type-check-timeout SECONDS	Unreleased: shared current/baseline checker budget, default 120; requires --type-check
--profile	Unreleased: profile static verification; human summary goes to stderr and JSON contains profiling
--profile-output <file>	Unreleased: save the profile separately; also enables profiling

Without --no-fail, skylos verify exits 1 for fail and 2 for incomplete. An incomplete result means Skylos could not establish a requested proof; it is not silently treated as a pass.

skylos done [path]

Run the repository's tests and completion checks and write a receipt. Settings come from the trusted baseline. --base REF compares against the merge base; without it, Done compares uncommitted changes against HEAD.

The unreleased source implementation also supports installed project type checking:

skylos done --base origin/main --type-check
skylos done --type-check --type-checker mypy

--type-check strengthens the type check to blocking. Its default is off; trusted [tool.skylos.done.checks] policy can select "block" or "advise". --no-tests does not disable an enabled type check. Set the Done compiler budget with type_check_timeout_seconds in trusted policy; the scan/verify --type-check-timeout flag does not apply to Done.

See Type Checking for configuration, diagnostic origins and incomplete comparisons.

skylos done map [path]

Show what a change touches: each changed Python or TypeScript/JavaScript function, method and class with its old and new code, calls added and removed, its callers and whether they were updated, removed security checks, breaking or compatible signature changes, and what to read first, read, skim or skip. Skip holds only changes whose logic is proven the same. The map is computed from the code, not by a model, and makes no network requests. See Change Map and the Agent Code Workflow.

skylos done map                          # uncommitted changes, compared with HEAD
skylos done map --base origin/main       # a pull request, compared with its merge base
skylos done map --format json            # for a review agent or script
skylos done --base origin/main --map     # the done verdict, then the map

Flag	Description
--base <ref>	Compare with the merge base of this ref. Default: HEAD (uncommitted changes only)
--format text|json|markdown	Output format. Default: text

Exit 0 when the map is shown and 2 when it cannot be built, for example when the base ref does not exist. The map has no verdict. skylos done --map prints it after the done verdict and never changes the verdict, receipt or exit code.

skylos setup [path] and skylos open [path]

skylos setup                 # once per repository; safe to run again
skylos setup --no-ci         # skip the PR check
skylos setup --no-codex      # leave Codex settings alone
skylos open                  # compare with origin/HEAD (else main or master)
skylos open --base origin/develop

skylos setup writes a block between skylos:start and skylos:end markers in CLAUDE.md and AGENTS.md, adds skylos to .mcp.json, runs codex mcp add skylos when Codex is installed, writes the PR check with skylos cicd init and builds the code map. It warns when your PATH or Codex points at a different Skylos. skylos open is skylos graph open with the base detected; its Check this change button runs skylos done and refreshes the Changes and Pipeline tabs. Walkthrough: Tutorial.

skylos graph [path]

Map every Python and TypeScript/JavaScript function, method and class (and Go, Java, Rust and PHP as a first pass, with calls matched by name): what calls what, which tests reach it, the answers those tests expect, and what each one does in plain English. With --since, every changed function gets a verdict, and "same logic" is shown only when it is proven. See Codebase Graph.

skylos graph                              # build .skylos/graph/, compare with HEAD
skylos graph open                         # local browser view (127.0.0.1 only)
skylos graph --since origin/main          # mark everything this branch changed
skylos graph show load_config --format json
skylos graph impact load_config
skylos graph describe                     # plain-English descriptions, your model key
skylos graph describe --via skylos        # Skylos writes them for credits (not live in Skylos Cloud yet)
skylos graph --since origin/main --upload # logic-change report to Skylos Cloud (not live in Skylos Cloud yet)

Subcommand or flag	Description
--since <ref>	Compare with this ref and give each changed function a verdict. Default: HEAD; none skips it
--format text|json	Output format. Default: text
--upload	Send the logic-change report to Skylos Cloud (not live in Skylos Cloud yet). Needs committed changes and skylos login or CI; the project must have Logic changes reports turned on (1 credit per pull request)
open	Build and open the local viewer; rebuilds when files change
show NAME / find QUERY / impact NAME	One function's card, a name search, everything that depends on it
areas [ID]	The codebase split into areas that work together, or one area's members
relevant FILE...	The code that matters most to these files, within --budget tokens (default 2,000)
changes --base <ref>	Changed functions with verdicts and evidence, in read first, read, skim and skip sections
describe	Plain-English descriptions with your own model key. --via skylos (not live in Skylos Cloud yet) uses Skylos's key: 1 credit per 100 functions, or per 20 changes with --changes
pending / import FILE	Let your coding agent write the descriptions. pending --changes --base <ref> lists changed code to explain
report --base <ref>	Build the report Skylos Cloud stores: verdicts and reasons, no source code

Building the graph runs none of the project's code and makes no network requests. Only describe (your key or --via skylos) and --upload send anything.

skylos preflight [ARTIFACT]

Check one exact local built GPU artifact against the machines declared in .skylos/gpu-targets.yml (or .yaml). This command inspects artifact evidence. It does not review source edits or scan packages for CVEs.

.skylos/gpu-targets.yml

version: 1
targets:
  - name: inference-t4
    vendor: nvidia
    driver: "535.104.05"
    compute_capability: "7.5"
    platform: "linux/amd64"

Inspect a local file or directory:

skylos preflight build/app

Local version-1 inspection supports Linux ELF/CUDA artifacts and requires a trusted NVIDIA cuobjdump installed outside the project and artifact. Skylos takes private file snapshots and never loads or executes target code.

You may omit ARTIFACT when .skylos/release.json names one project-relative artifact:

.skylos/release.json

{"version": 1, "artifact": "build/app"}

There are no preflight mode flags. The artifact and fleet contract define the check. A valid report is concise on a TTY and schema-version-1 JSON when stdout is redirected. Argument and adapter errors can be plain text and exit 2.

Status	Exit	Meaning
PASS	0	The exact identity and every fleet target pass all checks within the declared static scope
FAIL	1	Artifact evidence proves at least one fleet target incompatible
UNKNOWN	2	Evidence is missing, ambiguous, unsupported, incomplete, or input is invalid

A digest-pinned OCI reference is accepted as an identity, but this CLI never pulls or starts it and therefore returns UNKNOWN. A trusted library caller can supply digest-bound inspection facts to skylos.preflight.run_preflight.

Version 1 covers exact local identity, Linux ELF platform, selected executable fatbin architecture routes, a static packaged $ORIGIN CUDA runtime route, and documented driver-family compatibility. It does not establish runtime execution, workload correctness, memory demand, performance, nonselected or relocatable fatbins, per-kernel symbol parity, or Windows PE runtime imports. See Release Reliability for the evidence model and library API.

Here, a selected executable fatbin is the executable CUDA record set that cuobjdump --list-elf/--list-ptx selects. Its producer identifier groups the cubin and PTX records that must share a compatibility route. Every observed group needs native cubin coverage for PASS; PTX-only coverage remains UNKNOWN because static inspection does not prove the deployment driver's JIT path. Across checks and targets, FAIL wins over UNKNOWN, and UNKNOWN wins over PASS.

skylos image scan

Scan a digest-pinned remote registry image for package vulnerabilities. Install Trivy separately as a trusted executable on PATH, and provide registry network access and any required registry credentials:

skylos image scan IMAGE@sha256:<digest> \
  --platform linux/amd64 --fail-on high

This command checks CVEs. It does not check CUDA architectures, packaged CUDA runtime binding, or fleet driver compatibility; use skylos preflight for those artifact checks.

Without --fail-on, vulnerability findings are report-only and a completed scan exits 0. With --fail-on LEVEL, findings at or above that severity exit 1. Scanner or report incompleteness exits 2.

skylos suite [DIRECTORY]

Build one repository report from static analysis, technical debt, agent defense, and provenance. DIRECTORY defaults to the current directory; a file target is rejected.

skylos suite
skylos suite . --json -o suite.json

Use skylos <path> when you need only the source scan and its analyzer flags. Suite runs in the local process and uploads only with --upload, but its SCA and AI dependency stages may query OSV.dev and public package registries. Findings are report-only and do not change the default 0 exit. Operational, output, upload, and uploaded Cloud quality-gate failures are nonzero.

skylos defend [DIRECTORY]

Inspect recognized LLM integrations in Python and TypeScript/JavaScript source, score their deployment guardrails, and optionally emit evidence or gate by severity. DIRECTORY defaults to the current directory; files are rejected.

skylos defend .
skylos defend . --format md -o evidence.md
skylos defend . --fail-on critical

defend checks the implementation of an AI agent. It does not validate the current code edit like verify, inspect a built GPU artifact like preflight, or exercise a running endpoint like skylos agent test. See Agent Verification.

Findings are report-only and exit 0 unless --fail-on, --min-score, or an explicit policy requests a gate. Upload and requested gate failures exit 1. If no supported integration is detected, the empty result does not prove that an unsupported or unrecognized implementation has guardrails.

skylos agent harden

Print each coding agent's own settings that deny reads of credential files and limit Claude Code to this project's MCP servers, pinned to exact versions. It prints by default and writes nothing.

skylos agent harden
skylos agent harden --offline
skylos agent harden --write

Flag	Description
--path DIR	Project folder to read (default .)
--print	Print the settings and write nothing (the default)
--write	Merge the JSON settings into their files after you answer y; needs an interactive terminal
--offline	Do not look up versions; unpinned MCP servers are left out

Exit codes: 0 when the settings were printed or --write merged every file; 1 when you did not answer y or a file could not be written; 2 when --path is not a folder or --write runs without an interactive terminal (for example from an agent). See Harden The Agents' Own Settings.

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.

Source-Scan Output Options

The flags in this section belong to skylos <path>. Other commands have their own output contracts; in particular, preflight has no output-format flag and emits JSON for valid reports when stdout is redirected.

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, pretty, json, llm, github, gitlab, or concise output. concise prints IDE-clickable file:line RULE_ID message findings.
--output, -o <file>	Write results to a file
--tree	Display findings in a hierarchical tree 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  SKY-D001  Unused function: helper
src/test.py:5  SKY-D003  Unused class: LegacyClient

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

Finding Filters

Flag	Description
--severity LEVEL	Show findings at or above critical, high, medium, or low
--category CAT	Show one or more comma-separated categories: security, reliability, secret, quality, ai_defects, dead_code, or dependency
--select RULE	Report exact rule IDs, case-insensitively. Repeat the option or use commas; required analyzer families are enabled automatically
--file-filter PATTERN	Show findings whose file contains the given substring
--limit N	Limit displayed findings per category while retaining a summary of the remainder

--severity, --category, --file-filter, and --limit filter presentation. --select is different: it both enables the matching analyzer family and restricts results to exact rule IDs. Unknown IDs are configuration errors and exit 2.

# Gate only GPU source/build intent
skylos . --select SKY-GPU001,SKY-GPU002,SKY-GPU003 --gate --format concise

GPU leaf rules require a valid release contract. Selecting SKY-GPU001, SKY-GPU002, or SKY-GPU003 automatically retains prerequisite SKY-GPU000, so a missing or malformed contract remains visible and the gate cannot pass open.

Analysis Flags

Flag	Description
--danger, --security	Enable security plus deployment/runtime contract scanning. Non-security deployment and GPU results are reported under Reliability. --security is another name for --danger
--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
--sca	Scan dependencies for known vulnerabilities (OSV.dev), malware and supply-chain problems. With --diff or --diff-base it also reports weakened install hardening (SKY-SCA-HRD001). See Supply Chain
--review-upgrades	With --diff or --diff-base (implies --sca), download the old and new version of each npm or PyPI package the change upgrades and report new install hooks, .pth or sitecustomize code and other risky code (SKY-SCA-UPG001, SKY-SCA-UPG002). Never installs or runs them. Without --diff or --diff-base it only turns on --sca. An upgrade it could not check (unreachable registry, more than 100 changes, a changed lockfile over 64 MB or unreadable) stops a --gate run with exit 2. See Upgrade Review
--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

Reliability has no separate broad analysis flag. Use --danger (or -a) to run deployment/runtime contract analyzers, or use --select to enable exact Reliability rules. Use --category reliability only when you want to hide other categories from the displayed result.

See Release Reliability for Kubernetes exposure, GPU source/build intent, and exact built-artifact preflight.

Type Checking And Profiling (Unreleased)

These options require the unreleased source implementation. Use the help in your installed build to check availability.

skylos . --type-check --type-checker mypy
skylos . --diff origin/main --type-check
skylos verify src/app.py --type-check --profile
skylos . --format json --profile-output profile.json > findings.json

Flag	Behavior
--type-check	Execute installed mypy, Pyright, Pyrefly or tsc with project configuration. Configured plugins can execute; use a trusted repository
--type-checker auto|mypy|pyright|pyrefly|tsc	Select a configured checker. Multiple configured tools require an explicit choice. Requires --type-check
--type-check-timeout SECONDS	Shared current/baseline checker budget for scans and verify; default 120, greater than 0 and at most 3600. Requires --type-check
--profile	Measure Skylos's static scanner phases, Python functions and call counts. Does not enable checker, application or test execution
--profile-output <file>	Write standalone profiling JSON; enables profiling. Parent directory must exist; use a different path from --output

Compiler diagnostics appear in type_check, separate from Skylos rule findings. Without a baseline, current type errors block. With a comparable Git baseline, confirmed preexisting errors remain visible; introduced or unclassified errors block. A missing checker, unsupported comparison or checker failure is incomplete. Scans and verify exit 1 for type failures and 2 for an incomplete requested check; scan --force can override type failures, and verify --no-fail keeps its explicit override.

Profiling adds a human summary on stderr and a profiling object to JSON scan and verify reports. Profile output failures are operational errors (exit 2) even with --force. The compiler's separate time is type_check.seconds; --profile does not profile its subprocess.

See Type Checking and Analysis Profiling for baseline requirements, completion limits and the profile schema.

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 compare with the pull request's target branch on GitHub Actions, GitLab CI, Jenkins, Bitbucket Pipelines, Azure Pipelines, Buildkite, Travis CI, Drone and Woodpecker, else origin/main; see Other CI Providers. 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

# Compare with the pull request's target branch (detected per CI), else origin/main
skylos . --diff --danger --secrets --quality --ai-defects

For cross-file findings, Skylos also checks related_locations against the changed scope. A finding can therefore remain visible when the PR changes a supporting contract, manifest, source route, build file, or Dockerfile rather than only the finding's primary location. Required fail-closed prerequisites such as SKY-GPU000 are retained for selected leaf rules.

Agent-config and publish-job findings (SKY-D365 to SKY-D377) are judged differently. With --diff, one is new when the merge base did not have the same finding (rule, file, event or job name and command), even if its line did not change; with --diff-base alone, every such finding in a changed file counts. See How They Count In The Gate.

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.

Skylos Cleanup

skylos cleanup combines existing detector evidence with a prioritized queue, local history, named plans and limited deterministic edits. The default scan leaves source unchanged. Preview a patch for a selected task, then explicitly apply it and request the relevant tests:

skylos cleanup . --top 5
skylos cleanup . --next
skylos cleanup . --diff origin/main --context
skylos cleanup . --task TASK_ID
skylos cleanup . --task TASK_ID --apply --test-cmd "pytest -q test/test_orders.py"
skylos cleanup . --defer TASK_ID --reason "Review public callers first"
skylos cleanup . --restore TASK_ID
skylos cleanup . --history --format json

Flag	Description
--format human / --format json	Human output by default, or machine-readable JSON
--top N	Positive display limit for each queue; default 10
--all-advice	Include optional maintainability advice
--diff BASE	Scan the full Git project and display tasks in changed files; does not prove each finding is new
--from-report REPORT	Reuse analyzer JSON without rescanning; supply the original scan root as the path
--next	Show the next open task, or advice when no task is available
--task ID	Preview a supported deterministic patch; a unique task-ID prefix is accepted
--apply	Apply the selected patch and statically rescan; requires --task
--test-cmd COMMAND	Explicitly authorize this test command after applying; no shell interpretation
--junit-report PATH	Read the authorized runner's fresh project-relative JUnit report; pytest produces one automatically
--defer ID --reason TEXT	Defer local work without changing raw findings or gate policy
--restore ID	Return deferred work to the open queue
--history	Read local cleanup history without scanning
--no-state	Disable reading and writing cleanup history
--create-plan NAME --plan-task ID	Create an ordered local plan; repeat --plan-task for Python anchored tasks
--prerequisite TEXT, --acceptance-check TEXT	Store plan requirements as text; never executes them
--plan NAME, --plans	Inspect one plan or list local plans
--move-task ID --before ID	Reorder work in the selected plan
--complete-task ID --note TEXT	Record manual, unverified completion; stale steps require a note
--context	Add bounded source lines, static graph impact, candidate callers and suggested test files
--review	Send bounded context to the configured model for separately labeled advice
--reviews	Read saved cited advice with current/stale source status
--promote-review ID	Explicitly add current saved advice to the selected plan, retaining its advice label
--model, --provider, --base-url	Configure the optional model review

ready means work exists; clear means no visible work in the recorded scope. Both exit 0. Execution reports verified only when fresh observed tests pass and a complete comparable rescan removes the target without new defects or high-severity review findings. Skipped tests leave applied_unverified. Unavailable checks produce incomplete and exit 2; invalid input also exits 2. Failed checks exit 1 and attempt rollback while preserving intervening file changes. Read the test, rescan and rollback receipts. These are recorded checks, not universal behavioral proof or a security verdict. An opaque exit zero is insufficient: tests must be observed through fresh JUnit results. Test count and whether changed code was exercised remain separate. Apply scans check security/secrets as well as quality/AI-code/dead code; they do not enable dependency registry checks.

Edits support conservative Python SKY-U001, SKY-U002 and SKY-L038 cases, plus a narrow TypeScript/TSX same-directory singleton named import type removal. Unsupported or ambiguous cases require manual review; no compiler or package script runs by default. Named plans currently require Python anchors. Local history is stored in .skylos/cache/cleanup.json; absence becomes not_reported, not a verified fix. Saved reports cannot authorize edits, model review or history changes. --review is separate from patch application and requires the LLM extra and provider configuration. See Cleanup for the full workflow. Saved reviews retain citations, model/provider and source hashes unless --no-state is selected. Advice never authorizes edits or verifies a fix. Check installed skylos cleanup --help: new options describe current source and may not yet be in your packaged release.

The separate skylos clean command below retains its Python dead-code workflow.

Deterministic Cleanup

Use skylos clean for Python import and function cleanup. With no mode flag it asks about each candidate and can write files after final confirmation. --dry-run is the guaranteed no-write preview.

# Preview Python 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 uses Python LibCST codemods and path-containment checks. Automatic cleanup currently edits unused imports and unused functions only; classes, variables, other languages, and lower-confidence findings remain review items. The command currently exits 0 after a completed apply pass even if an individual transform failure was printed, so review the completion output.

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
Agent Behavior Contract	skylos agent init	Create .skylos/agent-test.yml for runtime response, tool, refusal, and source assertions
Agent Behavior Test	skylos agent test --allow-contract-endpoint	Explicitly allow and test the contract's loopback endpoint
Offline Agent Behavior Test	skylos agent test --observations agent-observations.json	Deterministically evaluate captured typed observations without a network call
Authenticated Remote Agent Test	skylos agent test --endpoint https://agent.example/v1/chat/completions --allow-remote --auth-env AGENT_TOKEN	Select the remote destination and bearer-token environment variable from the trusted CLI invocation
Bounded Agent Test	skylos agent test --max-scenarios 25 --max-seconds 300 --max-tokens 1024	Enforce scenario/time budgets and request an endpoint response-token cap
AI Security Scan	skylos agent scan . --security	Security taskflow audit with repo map, file facts, and verifier-backed evidence
Fix Suggestions	skylos agent scan . --with-fixes	Add suggestions without changing files
Automated Repair	skylos agent remediate .	Apply supported fixes and re-scan; tests and PR creation are explicit options
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 (Workspace plan)
Balance: 997 credits

Recent activity:
  +1000  Purchased 1000 credits (team pack)
  -3  Used feature: AI fix pull request

Buy credits: https://skylos.dev/dashboard/billing

Requires skylos login first. See Billing & Credits for pricing.

CI/CD Commands

skylos cicd init

Set up the pull request gate for the CI your repository uses. On GitHub Actions it generates a workflow with a PR quality gate, a Done job when tests are discovered, and a default-branch Cloud upload through GitHub OIDC. On GitLab CI, Jenkins, Bitbucket Pipelines, Azure Pipelines and CircleCI it writes that CI's file, or prints the block to add when the file already exists; see Other CI Providers. CIs other than GitHub Actions need Skylos 5.1.0 or newer.

The behavior and options in this section require Skylos 4.46.0 or newer. Skylos 4.45.0 has the older generator and does not accept --no-upload, --done or --default-branch.

python -m pip install --upgrade "skylos>=4.46.0"
skylos cicd init
skylos cicd init --no-upload

PR scan and Done jobs have no Cloud credentials or OIDC permission. The separate upload job runs only on default-branch pushes and needs the Skylos GitHub App installed on the repository. Inspect the generated test dependency step before making Skylos Done a required check.

Flag	Default	Description
--ci	detected	CI to set up: github, gitlab, jenkins, bitbucket, azure, circleci, or other (prints the commands to add).
--python-version	3.12	Python version for the workflow
--triggers	pull_request push	GitHub event triggers
--analysis	dead-code security quality ai-defects secrets dependency	Analysis types to enable
--no-baseline	false	Skip baseline comparison
--llm	false	Include LLM-enhanced analysis
--model	—	LLM model to use with --llm
--claude-security	false	Add a parallel Claude Code Security scan job.
--upload / --no-upload	on for GitHub Actions	Upload full scans on default-branch pushes with GitHub OIDC; no stored API key required. Use --no-upload for CI without Cloud. Other CIs get no upload job.
--done / --no-done	auto	Add Done when pytest tests or a configured [tool.skylos.done] test command are found; force or omit the job explicitly.
--default-branch	origin/HEAD, else main and master	GitHub Actions: the branch whose pushes upload. CircleCI and other CIs: the branch the gate compares with (origin/HEAD, else main).
--scan-path	.	Directory to scan, such as apps/api. Does not route the generated policy-sync step to a Cloud project subpath.
--risk-review	false	Add the Skylos risk review job. It fails while a pull request has risks, such as deleted tests or removed auth, that no person with write access approved. Bot approvals do not count.
--advisory-gate	false	Report quality-gate failures without failing the generated gate job.
--defend	false	Include AI Defense checks.
--output, -o	the CI's own file	Output file path, for example .github/workflows/skylos.yml or Jenkinsfile
--force	false	Replace an existing GitHub workflow without asking. The old file is kept next to it as <name>.bak.

--llm, --model, --claude-security, --defend, --risk-review, --advisory-gate, --done/--no-done, --triggers and --force apply to GitHub Actions only. On other CIs, Skylos says which of them were not used.

For multiple Cloud projects in a monorepo, use the GitHub App's generated per-root workflow. The CLI-generated skylos sync pull step sends no GitHub project-subpath header, so --scan-path alone can leave policy sync ambiguous.

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. Uploads never cost credits. skylos cloud adds --upload for you, and -a unless you name checks.
--strict	Fail on any finding. With --gate, use the strict gate rules; a coverage gap exits 2
--force, -f	Exit 0 when the gate fails (still uploads if --upload is set). An incomplete scan still exits 2

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 for the enabled or selected analyzers are exceeded.

Reliability is evaluated separately from Security and defaults to max_reliability = 0. A bare --gate does not enable every analyzer; combine it with explicit analysis flags or exact --select rules. 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 --secrets --quality --ai-defects --gate

# Targeted GPU release gate; SKY-GPU000 is retained automatically
skylos . --select SKY-GPU001,SKY-GPU002,SKY-GPU003 --gate

Other Options

Flag	Description
--version	Print version and exit
--verbose, -v	Enable verbose logging

Exit Codes

Exact meaning is command-specific; these are the common categories:

Code	Meaning
0	Command-specific success; report-only commands can still contain findings
1	Findings, a gate/policy decision, or another command-specific analysis or operational failure caused the command to fail
2	The invocation, configuration, or input was invalid, or the command could not produce a usable result safely

For example, skylos compare uses 0 for a usable receipt and 2 for an invalid, unsafe, or unusable comparison; it does not use 1. See Scanner Comparison.

Removed Legacy AI Flags

The main source-scan command no longer accepts --fix or --audit. Use skylos agent scan [path] for LLM-assisted review, skylos agent audit [path] for Deep Mode, and skylos agent remediate [path] when you intend to change files.

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

LLM-assisted audit:

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

Whitelist a dynamic pattern:

skylos whitelist 'handle_*'
skylos whitelist --show