CLI to Dashboard Workflow
This is the operational guide for the cloud workflow. It reflects the current skylos CLI and skylos-cloud app behavior.
Short version: run skylos cloud. It runs every check, shows the findings,
uploads them, and prints this branch's quality gate and one link to it. The first run opens
your browser to log in. See Cloud Platform
for what it sends and what it prints.
Use this page when you want to answer:
- Which command should I run?
- What gets stored locally vs in the cloud?
- When do I need a GitHub repo URL?
- How do policy, suppressions, custom rules, and CI fit together?
If you only want the feature overview, read Cloud Platform. For auth details, read Authentication. For CI examples, read CI/CD Integration. For security-team review and procurement posture, read Enterprise Trust.
Command Map
| You want to... | Use this | What it actually does |
|---|---|---|
| Scan, upload and see the gate | skylos cloud | Runs every check (-a) unless you name some, shows the findings, uploads them to Skylos Cloud, then prints this branch's quality gate and one link to it. The first run opens the browser login |
| Connect or switch the current repo's cloud project | skylos login or skylos project use | Opens the browser chooser, lets you pick or create a project, verifies the token, and links this repo |
| Upload with the manual flag | skylos . --danger --upload | The manual form of skylos cloud: runs the analysis you picked locally, then uploads findings and metadata to Skylos Cloud |
| Keep local policy in sync | skylos sync pull | Writes .skylos/config.yaml, which later scans apply, and .skylos/suppressions.json, which local scans don't read yet |
| See which project this repo uses | skylos project status | Shows the repo link and active project |
| List known linked projects | skylos project list | Shows locally saved projects from ~/.skylos/credentials.json |
| Switch or remove the repo link | skylos project use / skylos project unlink | Rebinds the repo or removes only the repo-to-project link |
| Check the saved cloud connection | skylos sync status | Verifies the saved token against /api/sync/whoami |
| Connect headlessly with an API key | skylos sync connect <token> | Stores the token and links the repo without browser auth |
End-to-End Flow
1. Start Local
You do not need the cloud to use Skylos.
skylos .
skylos . --danger --quality --secrets --ai-defects
skylos . --gate
Local-only mode is the right choice when you want:
- a fast developer scan
- no hosted state
- repo-local thresholds and exit codes
- no shared history or team review
Add the cloud when you want:
- scan history and trends
- project-level policy managed in the dashboard
- shared suppressions
- issue grouping and exception workflows
- GitHub App integration, deep links, or repo-bound OIDC uploads
2. Connect the Repo to Skylos Cloud
The first run of skylos cloud connects the repo for you. To connect without
scanning, or to switch to another project later, run:
skylos login
skylos project use uses the same browser chooser but is framed around selecting the project for the current repo.
What happens:
- The CLI opens
skylos.dev/cli/connect. - You sign in with GitHub if needed.
- You pick an existing project or create a new one.
- The CLI verifies the returned token with
/api/sync/whoami. - The CLI stores credentials and writes the repo link.
Files written locally:
~/.skylos/credentials.json<repo>/.skylos/link.json
link.json is the repo-to-project binding. credentials.json stores saved project tokens and metadata.
Switching projects
Re-running skylos login does not require a full disconnect. The chooser opens again. If you finish the flow with a different project, the repo link is updated. If you close the browser flow, the current project is kept.
Useful repo commands:
skylos project status
skylos project list
skylos project unlink
Headless or manual setup
If you do not want browser auth:
skylos sync connect
# or
skylos sync connect sk_live_xxx...
Get the API key from Dashboard -> Settings -> choose project -> API key.
3. Upload Scans
The one command:
skylos cloud
It runs every check (-a), shows the findings, uploads them, then prints this
branch's quality gate and one link to it. Name checks to run only those, for
example skylos cloud --danger --secrets. It takes the same scan flags as
skylos ., for example skylos cloud src --exclude build. See
What you see for example output.
The manual form is --upload on a scan. It uploads exactly the checks you
picked:
skylos . --upload
skylos . --danger --quality --ai-defects --upload
skylos defend . --upload
What happens on upload:
- Analysis still runs locally.
- The CLI resolves auth.
- Findings and scan metadata are sent to Skylos Cloud.
- Skylos Cloud stores the scan, groups issues, applies suppressions, and evaluates the project gate.
- The dashboard updates.
Skylos Cloud records server-side upload attribution for the resolved project and auth path. For API keys, the upload is tied to the resolved project key identity. For GitHub Actions OIDC, it is tied to verified GitHub OIDC claims and the matched repo/project binding.
What auth the CLI uses
The current token resolution order is:
SKYLOS_TOKEN- GitHub Actions OIDC
- the current repo link plus
~/.skylos/credentials.json - the legacy default saved token
- system keyring fallback
Linked repos upload when requested
Linking saves the upload destination and credentials. Plain scans stay local.
Run skylos cloud, or add --upload to a scan, to send a report:
skylos .
skylos cloud
skylos . --upload
The generated CI workflow has a separate upload job that passes --upload
on default-branch pushes.
Custom rules are loaded at scan time
If the CLI has a valid cloud token, it also asks Skylos Cloud for org-level custom rules during scan startup. Those rules are applied locally during analysis. They are not written by skylos sync pull.
4. What Appears in Skylos Cloud
Workspace navigation currently includes:
OverviewProjectsScansIssuesExceptionsRulesTrends
Each project currently has tabs for:
OverviewScansIssuesSuppressionsDefenseProvenanceSettings
In practice, the cloud split looks like this:
- CLI: runs analysis
- Cloud: stores history, groups recurring findings, applies shared policy, manages suppressions, and exposes team workflows
5. Configure the Project in the Dashboard
The main project management surface is:
Dashboard -> Settings -> choose project
That surface currently manages:
- repository URL
- API key rotation
- GitHub App installation
- Slack and Discord notifications
- team members
- workspace/project policy
- policy inheritance
Repo URL: optional for basic uploads, required for GitHub-native features
A project can stay cloud-only with no repo URL and still accept normal API-key uploads.
Set the repo URL when you want:
- GitHub Actions OIDC uploads
- GitHub App installation
- GitHub deep links
- PR-linked GitHub check runs and comments
- repo-aware default-branch resolution
OIDC requires a unique project for the verified repository and the project
subpath supplied by the request. Multiple projects in one monorepo work when
each request identifies its root, such as apps/api. If no project matches,
or several projects still match the repository and requested subpath, Cloud
rejects the upload. A request without a subpath is ambiguous when it matches
several projects.
6. Pull Cloud Policy and Suppressions Back Into the Repo
skylos sync pull
This writes:
<repo>/.skylos/config.yaml<repo>/.skylos/suppressions.json
Use it after:
- changing project policy in the dashboard
- adding or revoking suppressions
- changing gate mode or thresholds
- updating exclude paths or security contracts
Local config precedence
The local CLI does not treat the synced file as the only source of truth.
Current precedence is:
- Skylos defaults
.skylos/config.yamlfromsync pullpyproject.toml[tool.skylos]- CLI flags
That means dashboard policy can seed the repo, but local pyproject.toml and explicit flags can still override it for a given run.
7. CI/CD
There are two main cloud upload patterns.
GitHub Actions with OIDC
Use this for uploads from default-branch pushes without a stored API key.
PR scans and tests run separately, without Cloud credentials or OIDC.
skylos cicd init generates both paths; see CI/CD Integration.
The onboarding workflow and generator options described here require Skylos 4.46.0 or newer. Skylos 4.45.0 has the older generator.
Preconditions:
- the project is bound to the GitHub repository in dashboard settings
- the Skylos GitHub App is installed on the repository
- only the upload job has
id-token: write
This upload-only example assumes one Cloud project for the repository and
main as its default branch. Replace the branch name as needed. Use the
App's per-root workflow for multiple monorepo projects.
name: Skylos Cloud upload
on:
push:
branches: [main]
permissions:
contents: read
jobs:
cloud-upload:
if: github.event_name == 'push' && github.ref == format('refs/heads/{0}', github.event.repository.default_branch)
runs-on: ubuntu-latest
timeout-minutes: 15
permissions:
contents: read
id-token: write
steps:
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
with:
fetch-depth: 0
persist-credentials: false
- uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
with:
python-version: '3.12'
- run: python -I -m pip install "skylos>=4.46.0"
- run: skylos sync pull
- run: skylos . --danger --secrets --quality --ai-defects --upload
env:
SKYLOS_COMMIT: ${{ github.sha }}
SKYLOS_BRANCH: ${{ github.ref_name }}
Cloud rejects uploads from ordinary pull_request jobs. Its GitHub App has
a separate PR workflow with an unprivileged scanner and isolated trusted
policy and publishing jobs. Use that generated workflow for Cloud-verified
PR checks; do not add credentials to your PR tests.
The App's Done job selects test setup from the reviewed base branch. Python
test dependencies share the scanner's Python environment and must preserve
the selected Skylos version; setup stops with an error if installation
replaces it. Expected local build artifacts, such as *.egg-info/, must have
narrow ignore patterns in the reviewed base .gitignore. Done still requires
a clean checkout: do not hide source changes or ignore all untracked files.
Token-based CI
Use this in a trusted CI job for providers without OIDC or for explicit project selection. Keep stored tokens out of PR test jobs.
- name: Run Skylos
env:
SKYLOS_TOKEN: ${{ secrets.SKYLOS_TOKEN }}
run: skylos . --danger --quality --ai-defects --upload
Or run skylos cloud --gate with the same SKYLOS_TOKEN: it runs every
check, uploads, and exits 1 when the Skylos Cloud gate fails. See
which gate that is.
Sync pull in CI
If you want the CI runner to use the latest synced dashboard thresholds and suppressions locally before the scan, add:
skylos sync pull
The generated default-branch upload job authenticates policy sync with its
GitHub OIDC identity. For local use or CI without OIDC, provide a saved API
key or SKYLOS_TOKEN.
Generated workflows vs OIDC
On GitHub Actions, skylos cicd init generates a PR quality gate, a Done job
when pytest tests or a configured test command are found, and a separate
default-branch upload job using GitHub OIDC. Upload is on by default; use --no-upload to omit it.
Use --done or --no-done to override test discovery. Regenerate after
upgrading Skylos to update the installed-version pin.
For multiple Cloud projects in a monorepo, use the GitHub App's generated
per-root workflow. CLI --scan-path changes the scanned directory, but the
CLI-generated skylos sync pull step does not send a GitHub project-subpath
header and can fail with an ambiguous binding.
skylos sync setup
skylos sync setup asks for a token to connect the local repository and
scaffold hooks and workflow files. Its generated CI workflow scans PRs
locally and uploads default-branch pushes through GitHub OIDC. Use
skylos cicd init to generate the quality gate and discovered Done job.
8. How the Cloud Gate Decides Pass or Fail
This is the key difference between --gate and --upload.
Local gate
skylos . --gate
Local gate uses local findings and local config. It only controls the CLI exit code.
Cloud gate
skylos cloud
# or the manual form
skylos . --upload
Cloud gate uses the project in Skylos Cloud and evaluates:
- the effective project policy
- active suppressions
- strict mode
- AI assurance, if enabled
- PR diff data when available
- otherwise the latest successful or overridden baseline scan on the same branch, or the default branch
That is why a repo linked to the dashboard can behave differently from a local-only run.
skylos cloud --gate exits 1 when this Skylos Cloud gate fails. It does not use
your local limits: skylos . --gate is a different, local gate that uses
[tool.skylos.gate] and uploads nothing.
A token does not pass the gate; fixing the issues does. See Do I need a key to pass the gate?
9. Recommended Rollout
A clean team rollout usually looks like this:
- Start with local scans only.
- Run
skylos cloudfrom a developer machine. The first run connects the repo; the upload checks the connection. This scan is unverified and cannot pass the Cloud GitHub gate. - Set the project repo URL if you want GitHub-native features.
- Configure policy in Governance → Policy.
- Run
skylos sync pullso the repo has the latest synced config and suppressions. - Install the GitHub App, then generate CI with
skylos cicd init: PR checks plus default-branch OIDC uploads. - Check that the expected PR jobs run, then require them: the project's Settings has Download ruleset for GitHub (how).
Troubleshooting
A linked scan does not appear in Cloud
Linking alone does not enable scan uploads. Run skylos cloud, or add
--upload to a scan, to send the report.
OIDC says the repo is not linked
Save the exact GitHub repo URL on the project in dashboard settings.
OIDC says the repo binding is ambiguous
Check the requested project subpath and remove duplicate bindings for the
same repository and subpath. For multiple monorepo projects, use the App's
per-root workflow; CLI --scan-path alone does not route policy sync.
skylos sync pull says not connected
Run skylos cloud, skylos login or skylos sync connect first.
The repo is connected to the wrong project
Use:
skylos project unlink
skylos login
Custom rules do not appear locally
Custom rules are loaded from the cloud only when a valid token is available. Paid-plan custom rule features also require the right plan.