Skip to main content
The native CLI connects to hosted Diffraction. It is separate from the contributor pnpm local:review harness. Version 0.1.1 has macOS and glibc Linux executables for arm64 and x64; Windows and Alpine/musl are not supported. macOS x64 is built but still awaits verification on Intel hardware.
CLI commands and source review execution are implemented. Full authenticated production API and commit/local-source-to-evidence verification remain incomplete. The public 0.1.1 installer was executed in a fresh macOS arm64 prefix and the installed binary returned the correct version. That installation check does not establish a completed hosted review.

​
Install

The release installer is served at:
It checks release and executable SHA-256 values and installs into ~/.local/bin without Node.js, npm, or sudo. It prints PATH instructions without editing your shell startup files. Rerun it to upgrade. To select a user-owned location:
If the endpoint is unavailable, do not replace it with an unofficial binary. Contributors with the source checkout can use pnpm --filter @diffraction/cli start -- help with Node.js 24 and pnpm.

​
Sign in

Choose Read only (default) or Read & write, or set it explicitly:
WorkOS handles browser authorization and the loopback callback at http://localhost:53682/callback. --no-browser prints the authorization URL for manual opening. Current consent scopes, repository/workspace permissions, developer eligibility, and the workspace write ceiling still apply. Broad consent does not grant administrator permissions. Credentials are private files under ~/.config/diffraction. Refresh and logout serialize access across processes. diffraction logout removes local credentials; it reports remote revocation only when the provider advertises and accepts it.

​
Read reviews and evidence

Replace the placeholder IDs with values returned by the preceding commands.
Evidence downloads verify recorded MIME type, size, and digest and never overwrite an existing file. Comments are read-only through the CLI. --json gives machine-readable output. History supports --limit and --before pagination.

​
Create a hosted review

These commands use real workspace review credits and require write access:
The CLI prints a request key. Reuse it with --request-key <key> to retry the same request and source. A new key deliberately creates another paid review. Exact commit and local-source reviews do not publish PR comments or Checks.

​
Review uncommitted changes

Git and an existing local HEAD commit are required for source collection. The base may be unpublished; the current changes need no new commit. First inspect the selected files:
Tracked working-tree files are included subject to exclusions. Select each wanted untracked file with --include:
The second command privately uploads selected bytes and requests fresh isolated hosted execution. It needs no commit, push, or PR. .diffractionignore and mandatory secret/generated-path exclusions apply. Symlinks are excluded or rejected, and unsafe paths are rejected; collection is bounded to 4,000 files, 2 MB per file, and 12 MB total source. Secret detection cannot prove arbitrary files contain no private data. See source privacy and retention.

​
Context and rules

Omitting --repo selects organization context. The rules file is a JSON array of strings. Writes require the relevant consent and current administration permission and use version checks. They update the same canonical settings as the website without rewriting historical run snapshots or starting a review.

​
Exit codes and configuration

JSON failures include a stable error code. Inspect findings, execution, and delivery status before interpreting a terminal failure. For another configured deployment, --config <file.json> accepts resource, issuer, and clientId; non-secret server configuration belongs in that file, not environment variables.