CLI

1. Install

Self-contained binaries — no .NET SDK and no repository clone. The installer verifies SHA256 and puts signaldiff on your PATH.

Windows

irm 'https://signaldiff.dev/install/cli.ps1' -OutFile "$env:TEMP\signaldiff-install-cli.ps1"
& "$env:TEMP\signaldiff-install-cli.ps1"

Linux / macOS

curl -fsSL 'https://signaldiff.dev/install/cli.sh' | bash

Open a new terminal so PATH updates apply (Linux/macOS: ~/.local/bin). Manual zips and checksums: downloads/cli. RID zips are typically about 30–32 MB to download (compressed single-file publish); size changes apply after the next cli-v* release. Pin a version with -Version / --version (published zips stay in blob storage). Contributors can still dotnet run --project SignalDiff from a clone.

Update

signaldiff update
signaldiff update --check

Replaces the current install with the latest published release (SHA256 verified). Use --check to report availability without downloading. --version pins a release; --force reinstalls the same version. .NET global tool installs should use dotnet tool update -g SignalDiff.Cli instead.

2. First command (local, free)

Pass --sitemap (no subcommand) to crawl from this machine and write an HTML report. No sign-in and no API key. signaldiff with no arguments prints help and exits 1 — it does not start a crawl.

signaldiff --sitemap https://example.com/sitemap.xml --output seo-report.html

Optional: --output (report path; missing parent directories are created before crawling), --max-pages (cap pages fetched; 0 / omitted is unlimited and warns on stderr), and --quiet (short summary on stdout; crawler logs at Warning+ on stderr). Crawler progress logs go to stderr; summary and report path stay on stdout. --json is for cloud subcommands only — with a local --sitemap crawl it exits 1 (HTML report remains the local output).

3. Use with AI coding tools

Paste this into Cursor, Copilot, Claude Code, or any coding tool that can run a terminal. It installs the CLI, runs a local crawl, and reads the report. Cloud commands run only if SIGNALDIFF_API_KEY is already set.

Install the Signal Diff CLI from https://signaldiff.dev/docs/cli (no .NET SDK required).

Windows:
irm 'https://signaldiff.dev/install/cli.ps1' -OutFile "$env:TEMP\signaldiff-install-cli.ps1"
& "$env:TEMP\signaldiff-install-cli.ps1"

Linux/macOS:
curl -fsSL 'https://signaldiff.dev/install/cli.sh' | bash

Open a new terminal, then crawl this sitemap locally:
signaldiff --sitemap https://example.com/sitemap.xml --output seo-report.html

Read seo-report.html and summarize SEO and crawl issues with suggested fixes.

If SIGNALDIFF_API_KEY is set, use cloud commands instead (base URL https://signaldiff.dev/api — include /api):
signaldiff sites list
signaldiff runs summary <runId>
signaldiff diff get <runId>

4. Cloud commands

Subcommands (sites, runs, diff, findings, scan) call Signal Diff in the cloud and need a paid API key.

signaldiff sites list
signaldiff runs list --site example.com
signaldiff runs get <runId>
signaldiff runs summary <runId>
signaldiff diff get <runId>
signaldiff findings list <runId> --severity Error --limit 50
signaldiff scan start --sitemap https://example.com/sitemap.xml
signaldiff scan wait <scanId> --json
signaldiff scan get <scanId>
signaldiff scan cancel <scanId>

Add --json for scripting on cloud commands (tables and key-value text are the default). Contract: success JSON on stdout; failures are one JSON object on stderr (error, optional statusCode / retryAfterSeconds — e.g. 401 unauthorized or 429 with retry-after) so pipes stay clean. Local --sitemap crawls reject --json (exit 1, no crawl). scan wait exits 0 when the scan completes and 1 when it fails; --interval (seconds, default 2) and optional --timeout control polling.

{
  "error": "Rate limit exceeded.",
  "statusCode": 429,
  "retryAfterSeconds": 30
}

Customer-hosted crawls: scan start --execution-mode Agent --agent-pool-id <pool> (see Customer agent setup).

5. Authentication

Cloud commands need a paid key from Developers → API keys. The same secret value works for GitHub Actions; the environment names and base URL differ.

Linux / macOS

export SIGNALDIFF_API_KEY=sck_…
export SIGNALDIFF_API_BASE_URL=https://signaldiff.dev/api

Windows PowerShell

$env:SIGNALDIFF_API_KEY = "sck_…"
$env:SIGNALDIFF_API_BASE_URL = "https://signaldiff.dev/api"

Staging: https://staging.signaldiff.dev/api. Flags --api-key and --base-url override the environment; the flag is visible in process lists—prefer the variable in CI.