Developer experience

Unveilr is designed so the default path is local, offline, and fast — and the path into the console, CI, and runtime is a short hop when you're ready. This page is the DX / integration-experience contract.

Time to first value

Step	What you do	What you get
1	Install CLI (partner binary / make install) then unveilr scan	AI-BOM + findings on your laptop — no account
2	Add unveilr/scan-action in observe	PR annotations, never fails the build
3	unveilr login + scan --upload	Org inventory, triage, evidence
4	Route agents through the Gateway	Runtime allow/deny with audit

Nothing in steps 1–2 requires the console. Security can adopt later without blocking developers today.

CLI — the primary surface

# Works today: partner binary or `make install` — see Installation.
# After GA CDN is live: curl -fsSL https://get.unveilr.ai/install.sh | sh
cd your-repo
unveilr scan                 # observe (exit 0)
unveilr scan --json          # editor / script friendly
unveilr scan --sarif out.sarif
unveilr scan --diff pr.diff  # judge only added lines
unveilr scan --mode enforce --fail-on high

DX properties that matter in practice:

• Offline & deterministic — same repo → same findings; safe as a CI gate.
• No network on scan — source stays local unless you --upload.
• Machine-readable outputs — --json / --sarif for IDE, bots, and pipelines.
• Diff-aware — PRs aren't failed for pre-existing debt they didn't introduce.
• Monitor Mode — observe everywhere first; enforce per repo when ready.

export UNVEILR_API=https://guard.unveilr.ai   # see Production APIs
unveilr login --token "$UNVEILR_TOKEN" --api "$UNVEILR_API"
unveilr scan --upload

Hosted origins, service tokens, and role-based access: Production APIs.

IDE — findings where you write

The VS Code extension (works in Cursor and other VS Code forks) runs unveilr scan --json and surfaces diagnostics in the Problems panel (severity-mapped, optional scan-on-save). Point unveilr.cliPath at the binary if it isn't on PATH.

Integration experience: same detector floor as CI — no “works on my machine” gap between local and pipeline.

Screenshot to capture — IDE Problems

Where: VS Code / Cursor with the Unveilr extension enabled on a representative repository. Capture: Problems panel listing Unveilr findings next to an open file with a highlighted insecure line.
Story it tells: “Security feedback at the keystroke, not only in CI.”

CI & GitHub Action — one YAML block

- uses: unveilr/scan-action@v1
  with:
    mode: observe     # start here — never fails the build
    fail-on: high

Findings land as inline PR annotations (SARIF → code scanning). Flip mode: enforce when the signal is trusted. Optional upload: "true" streams results into the console with a service token.

Full company wiring (GitLab, Jenkins, ingest, tickets): Integrations.

Screenshot to capture — PR annotations

Where: GitHub PR → Files changed / Checks, or Security → Code scanning.
Capture: Unveilr finding annotation on an added line.
Story it tells: “We gate AI risk on the diff that introduced it.”

Console onboarding — guided setup

After login, Get started (/onboarding) walks connect-repo → first scan → review findings → wire notifications / SSO. Use it for controlled company rollouts.

Screenshot to capture — Onboarding

Console path: /onboarding
Capture: checklist with at least one completed step and the next action clear.
Story it tells: “Minutes from signup to a populated AI-BOM.”

Service tokens for pipelines

Mint once in Settings → API Tokens (/settings/tokens):

• Tenant-scoped, optional expiry, revocable immediately.
• Shown in full once; console stores a hash.
• Can upload scans; cannot mint or revoke other tokens (no privilege escalation from a leaked CI secret).

unveilr login --token "$UNVEILR_TOKEN" --api https://your-instance
unveilr scan --upload

Screenshot to capture — API Tokens

Console path: /settings/tokens
Capture: token list (names, expiry, last used) — never show a live secret.
Story it tells: “CI auth is first-class and revocable.”

Govern without rewriting agents

Afternoon path: Console → Agents → Register → Approve → On-ramp → one POST /v1/govern/check (or MCP Gateway URL). Customer cookbooks: Govern check. Full operator guide in the repo: docs/GOVERN_ONRAMP.md.

pip install -e sdk/python
export UNVEILR_API=… UNVEILR_AGENT_TOKEN=uvt_…

from unveilr import govern

@govern(tool="ledger.query", server="ledger")
def query_ledger(sql: str): ...

MCP clients: point at https://gateway/mcp/{tenant}/{server}, start in observe, then enforce. Structural protections stay hard in both modes.

Org hooks: SIEM channel type, policy packs (pack-dev-observe → pack-production), Jira/ServiceNow tickets.

For policy authoring, keep the gateway API-backed (GATEWAY_CONTROL_PLANE=api) so console changes refresh enforcement immediately. The Policies workbench supports disabled drafts and exact-engine simulation before rollout.

Details: Govern · Integrations → Agent runtime.

DX anti-patterns we avoid

Anti-pattern	Unveilr choice
“Install our agent to scan”	Local CLI; optional upload
Fail CI on day one	Monitor Mode default
Separate local vs CI rules	One deterministic detector floor
Opaque “AI risk score” only	Findings with path, rule, severity + blast-radius
Compliance auto-green	Evidence + human attestation

Where to next

• Quick start — five-minute path.
• CLI reference — flags and exit codes.
• Integrations — company-wide rollout.
• Screenshot guide — documentation capture checklist.