CLI reference

The desktop app is the daily driver. The CLI is what you reach for when you want SiteCMD inside an automated pipeline: a CI job, a pre-push hook, a deploy gate, a cron-driven scan.

The sitecmd binary is a single self-contained binary for Linux, macOS, and Windows. Its six local commands need no account and run Web Scan or Code Scan without a UI. Its three connected commands add shared-baseline gates, deployment records, and connected-service submissions for an already connected site.

Local scan runs Web Scan against a live URL. Local audit runs the complete Code Scan against a source checkout. The connected gate and connected --submit commands run that same Code Scan and add hosted baseline or deployment context. Core Web Vitals and the axe-core accessibility deep scan remain desktop-only because the release CLI does not bundle a browser engine.

This page is the reference: what every command does, every flag, every exit code. For task-oriented usage, see Quality gates in CI and Pre-push hooks.

Installation

On macOS and Linux, install Minisign first (brew install minisign on macOS, or use your Linux package manager). The installer then downloads the latest release, verifies both its checksum and signature, confirms the binary reports the requested version, and installs sitecmd onto your PATH:

curl -fsSL https://sitecmd.com/install.sh | sh

The script installs to /usr/local/bin when writable, otherwise ~/.local/bin. Set SITECMD_INSTALL_DIR to choose a different directory, or SITECMD_VERSION to pin a specific version.

On Windows, download the zip directly and put sitecmd.exe somewhere on your PATH:

https://releases.sitecmd.com/v<version>/sitecmd-cli_<version>_windows-x86_64.zip

Direct downloads for every platform follow the same pattern (darwin-universal.tar.gz, linux-x86_64.tar.gz, windows-x86_64.zip), each with .sha256 and .sig sidecars next to it. The signature uses the same minisign trust root as desktop updates. The CLI is versioned in lockstep with the desktop app; https://releases.sitecmd.com/ reports the latest version. macOS and Windows binaries are also code-signed with the same identities as the desktop app.

Commands

The CLI exposes nine subcommands:

Command	What it does
init	Set up a .sitecmd/ project config in the current directory.
audit	Run the free local Code Scan against a source checkout.
scan	Run a scan and write results to .sitecmd/ (or stdout with --json).
fix	Output fix prompts from the last scan.
watch	Re-scan on an interval.
check	Regression check designed for git hooks.
connected	Preview or submit connected code evidence for a deployment.
deploy	Record a deployment without attaching code evidence.
gate	Compare checkout findings with the connected baseline.

Run sitecmd <command> --help for the full flag list per command.

sitecmd audit

Runs Code Scan against a source checkout without an account, license, desktop database, or connected-service credential.

sitecmd audit .
sitecmd audit . --format review --output sitecmd-review.md
sitecmd audit . --format github --fail-on high

Flag	What it does
<path>	Project root to audit. Required.
--format <FORMAT>	summary, json, markdown, review, or GitHub annotations via github.
--fail-on <SEVERITY>	Exit 1 when a critical, high, medium, or low finding meets the selected floor.
--output <PATH>	Write the rendered report to a file instead of standard output.
--inspect-local-databases	Opt this run into reading local dotenv values for target discovery and read-only inspection of schema and migration metadata, never application table rows. SQLite must be inside the checkout; every Postgres host must be loopback or a local Unix socket. Remote targets are rejected.

Without --inspect-local-databases, audit does not read values from local non-example dotenv files or open a project database. Connected and CI commands do not enable this option implicitly.

Exit code 0 means the audit completed without meeting the configured threshold. Exit code 1 means a finding met --fail-on. Exit code 2 means the audit could not run or the report could not be written.

sitecmd init

Bootstraps a .sitecmd/ directory at the project root.

sitecmd init [url] [options]

Flag	What it does
[url]	Positional. The site URL for this project.
--name <NAME>	Project name (defaults to the directory name).
--yes, -y	Non-interactive mode (use detected values without prompting).
--no-deep-link	Skip opening the desktop app after init.

init writes two files into .sitecmd/:

• config.json - project URL, default scan type, and environments. No score threshold is written by default; add a fail_under value here (or pass --threshold) to arm sitecmd check.
• .gitignore - preconfigured to commit config.json (and itself) while ignoring result files.

After your first sitecmd scan, the directory also holds the result artifacts: last-scan.json (the raw result --diff compares against), issues.md (agent-readable fix instructions), issues.json (machine-readable summary), and rules.md (preventive coding rules derived from what failed).

Commit .sitecmd/config.json so your team and CI share settings. The result files are gitignored by default.

When the desktop app is installed on the same machine, init and scan also sync the project into the app’s local database and hand off via a sitecmd:// deep link, so CLI scans show up in the app. --no-deep-link skips that for init; --json scans skip it too.

sitecmd scan

Runs a scan against the configured (or passed) URL.

sitecmd scan [options]

Flag	What it does
--url <URL>	URL to scan. Falls back to .sitecmd/config.json if omitted.
--type <TYPE>	Scan type: health, security, accessibility, polish. Default: health.
--diff	Compare with the last scan and show what changed.
--env <NAME>	Use a named environment URL from config.
--fail-under <N>	Exit 1 if the score is below N. The quality-gate flag.
--json	Output JSON to stdout, skip writing to .sitecmd/.
--output json	Alias for --json.
--timeout <SECS>	HTTP timeout per request. Default 30s.
--categories <LIST>	Comma-separated health-scan filter: security, seo, performance, accessibility, compliance, or config. Unknown names fail instead of producing a partial gate.
--no-browser	Skip browser-based checks in a browser-enabled source build.
--cwv	Measure Core Web Vitals in a browser-enabled source build. The signed release binary rejects this flag because it deliberately ships without a browser engine.

Exit codes

Code	Meaning
0	Scan passed (or no threshold set).
1	Score below the --fail-under threshold, or a new critical in --diff mode.
2	Scan error (network problem, invalid URL, etc.).

These exit codes are the basis for every CI integration. See Quality gates in CI.

Examples

# Scan with current config
sitecmd scan

# Scan a specific URL
sitecmd scan --url https://example.com

# Quality gate: fail the build if security score drops below 90
sitecmd scan --type security --fail-under 90

# Diff against last scan
sitecmd scan --diff

# Pipe results to a file for further processing
sitecmd scan --json > results.json

sitecmd fix

Outputs fix prompts from the most recent scan.

sitecmd fix [options]

Flag	What it does
--all	Show all matching issues (default: the top issue only).
--id <CHECK_ID>	Show the fix for a specific check ID.
--type <TYPE>	Filter by issue type.
--category <CAT>	Filter by category.

Without --all, fix prints one prompt - the highest-priority match - and notes how many more are available. Useful for piping into an AI tool from a script, or for printing the next thing to do after a CI scan.

sitecmd watch

Re-scans on an interval. Useful when you’re actively fixing issues and want to see them tick down.

sitecmd watch [options]

Flag	What it does
--url <URL>	URL to monitor.
--interval <SECS>	Rescan interval. Default 300s (5 minutes).
--env <NAME>	Use a named environment from config.

sitecmd check

Regression check designed for git hooks.

sitecmd check [options]

Flag	What it does
--install	Install as a git pre-push hook.
--strict	Also fail on any new issue vs the last scan. Always runs a fresh scan.
--threshold <N>	Minimum score to pass (defaults to fail_under in config).

The default mode compares the score against the threshold, reusing a cached last-scan.json when it’s less than 24 hours old (so a push right after a scan doesn’t re-scan). With no threshold configured, the default mode passes and says so; set fail_under in .sitecmd/config.json, pass --threshold, or use --strict. Strict mode always scans fresh and fails when any failing check wasn’t failing in the previous scan, on top of the threshold gate.

See Pre-push hooks for the recommended setup.

sitecmd connected

Previews the exact connected payload or audits the checkout and submits code evidence for a deployment.

sitecmd connected --dry-run --connection-export ./connection.json

sitecmd connected --submit --connection-export ./connection.json \
  --deployment-id run-42 --commit c0ffee1

Flag	What it does
--dry-run	Print the exact payload without sending it.
--submit	Audit this checkout and send its code evidence for a deployment.
--connection-export <PATH>	Encrypted, credential-free export created by the desktop app. Required.
--passphrase-env <NAME>	Read the export passphrase from this variable. Default: SITECMD_CONNECTION_PASSPHRASE.
--token-env <NAME>	Read the CI token from this variable. Default: SITECMD_CI_TOKEN.
--deployment-id <ID>	Provider identity for the deployment. Required with --submit.
--commit <SHA>	Commit carried by the deployment. Required with --submit.
--ref <REF>	Git ref deployed.
--previous-sha <SHA>	Commit the deployment replaced.
--target <NAME>	Provider deployment target.
--deployed-at <TIME>	Provider creation time.
--published	Explicitly assert publication. Normally derived from the live ordering cursor.
--ordering-authority <ID>	Advanced override for the selected publish namespace.
--ordering-epoch <N>	Advanced override for the selected authority epoch.
--publish-sequence <N>	Advanced first-publication ordinal. Use this or a predecessor, never both.
--predecessor-deployment-id <ID>	Advanced exact predecessor identity. Use this or a sequence, never both.
--path <PATH>	Project root to audit. Default: current directory.
--db <PATH>	Desktop database path, overriding SITECMD_DB_PATH and the platform default.

Without deployment flags, --dry-run prints the same desktop submission serialization used by Sync Now. With deployment flags, it prints the CI payload before server-derived ordering. A real GitHub Actions submission with its OIDC witness reads the site’s deployment ordering cursor and automatically attaches the next causal publish fact: the first publish advances the seeded sequence, and later publishes name the exact current deployment as predecessor. A generic credential, including one used from GitHub Actions, reports its unattested mode through that cursor read, requests no OIDC witness, and submits the same deployment as history without failing. A dry run contacts nothing, so include the advanced ordering flags only when you need to preview those exact fields. A successful submission records or converges on the deployment and sends the checkout’s code findings. Repeating the same payload is safe.

CI evidence has two trust levels. A non-GitHub runner can submit unattested evidence: findings can establish presence, but cannot mark anything fixed or advance lifecycle state. A correctly pinned GitHub Actions job earns exact provenance. Create its token in the desktop with Repository and Trusted workflow filled in; SiteCMD resolves and pins GitHub’s immutable repository ID as well as the workflow and optional ref.

GitHub Actions submissions require the job permission below. The CLI uses GitHub’s runner-provided OIDC variables automatically, requests the connected-service audience, and sends the short-lived GitHub OIDC witness beside the SiteCMD CI token. Do not copy or create the ACTIONS_ID_TOKEN_REQUEST_* variables yourself.

permissions:
  contents: read
  id-token: write

steps:
  - uses: actions/checkout@v4
  - name: Submit SiteCMD evidence
    env:
      SITECMD_CI_TOKEN: ${{ secrets.SITECMD_CI_TOKEN }}
      SITECMD_CONNECTION_PASSPHRASE: ${{ secrets.SITECMD_CONNECTION_PASSPHRASE }}
    run: >-
      sitecmd connected --submit
      --connection-export ./connection.json
      --deployment-id "${{ github.run_id }}-${{ github.run_attempt }}"
      --commit "${{ github.sha }}"
      --ref "${{ github.ref }}"

If permissions: id-token: write is missing, the CLI fails visibly instead of silently downgrading the submission. If the repository ID, workflow, ref, or commit does not match the token’s pins, the service rejects the witness.

sitecmd deploy

Records a deployment without running a code scan. Use it in a deployment pipeline whose scanner runs elsewhere.

sitecmd deploy --site site_123 --deployment-id run-42 --commit c0ffee1

Flag	What it does
--site <ID>	Connected site ID. Use this or --connection-export.
--connection-export <PATH>	Read the site ID from an encrypted connection export.
--passphrase-env <NAME>	Read the export passphrase from this variable. Default: SITECMD_CONNECTION_PASSPHRASE.
--token-env <NAME>	Read the CI token from this variable. Default: SITECMD_CI_TOKEN.
--deployment-id <ID>	Provider identity for the deployment. Required.
--commit <SHA>	Commit carried by the deployment. Required.
--ref <REF>	Git ref deployed.
--previous-sha <SHA>	Commit the deployment replaced.
--target <NAME>	Provider deployment target.
--deployed-at <TIME>	Provider creation time.
--published	Explicitly assert publication. Normally derived from the live ordering cursor.
--ordering-authority <ID>	Advanced override for the selected publish namespace.
--ordering-epoch <N>	Advanced override for the selected authority epoch.
--publish-sequence <N>	Advanced first-publication ordinal. Use this or a predecessor, never both.
--predecessor-deployment-id <ID>	Advanced exact predecessor identity. Use this or a sequence, never both.

The command reads the site’s deployment ordering cursor and attaches the next causal publish fact automatically. The explicit ordering flags are advanced overrides for providers that already supply an attested sequence or predecessor. Redelivering identical deployment facts converges on the stored record. Reusing a deployment ID with different immutable facts, including its commit, ref, predecessor SHA, target, or provider creation time, is an error.

sitecmd gate

Audits the checkout, asks the connected service which findings are new against its shared baseline, and discards the candidate after rendering the verdict.

sitecmd gate --connection-export ./connection.json --threshold high

Flag	What it does
--connection-export <PATH>	Encrypted, credential-free export created by the desktop app. Required.
--passphrase-env <NAME>	Read the export passphrase from this variable. Default: SITECMD_CONNECTION_PASSPHRASE.
--token-env <NAME>	Read the CI token from this variable. Default: SITECMD_CI_TOKEN.
--threshold <LEVEL>	Fail at or above critical, high, medium, or low. Default: high.
--strict	Also fail when detector or corpus drift prevents a confident comparison.
--path <PATH>	Project root to audit. Default: current directory.
--db <PATH>	Desktop database path, overriding SITECMD_DB_PATH and the platform default.

Exit code 0 means the candidate passed. Exit code 1 means the merge is blocked by the verdict. Exit code 2 means the gate could not run, which is an operational failure rather than a quality decision.

Core Web Vitals and axe-core

Core Web Vitals (Largest Contentful Paint, First Contentful Paint, Cumulative Layout Shift, Time to First Byte) and the axe-core accessibility deep scan run a real browser, and the standalone CLI binary ships without the browser engine. Run them from the desktop app instead.

The CLI’s live-site checks already cover performance signals without a browser: response time and TTFB, compression, caching headers, render-blocking resources, and image hygiene. For the static accessibility checks the CLI runs, see Live-site checks.

Authentication and data

The six local commands do not require a login, license, or SiteCMD server. Project-aware commands write their artifacts to the local .sitecmd/ directory; audit writes to standard output unless --output is set.

The three connected commands call the connected service in their networked modes. They use the site-scoped token named by SITECMD_CI_TOKEN; connected and gate also open an encrypted connection export so the checkout can derive the same privacy-preserving finding identities as the desktop. The export contains no bearer credential, and no command needs a desktop license key in the CI environment. connected --dry-run is the exception: it contacts nothing.

Consequences:

• Every local command is free. sitecmd audit, sitecmd scan, sitecmd check, and sitecmd fix run with no license. Code findings, fix prompts, and framework-specific guidance are part of the complete local workbench.
• Artifacts contain complete finding context. Exported .sitecmd/ files carry the same finding detail and fix guidance regardless of subscription state; there is no local redaction layer.
• No shared history. The CLI’s .sitecmd/ directory is local to wherever it ran. If you want shared history across machines, run the desktop app on one machine and use the CLI for ephemeral CI checks.

Connected CI does not turn on extra local finding fields. It adds shared history, deployment binding, baseline comparisons, and server-assigned provenance around the same local scanner output.

When to use CLI vs. desktop

Use the desktop app for	Use the CLI for
Day-to-day triage	CI quality gates
Reading scan results in detail	Headless scans on schedules
Connecting integrations	Pre-push git hooks
AI editor workflows (via MCP)	Build pipelines
Long-running history	One-shot regression checks

The two are designed to coexist. Many teams run the desktop app locally for triage and the CLI in CI for enforcement.