> ## Documentation Index
> Fetch the complete documentation index at: https://docs.diffraction.sh/llms.txt
> Use this file to discover all available pages before exploring further.
# CLI
> Connect with WorkOS, inspect evidence, and request PR, commit, or local-source reviews.
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:
```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
curl -fsSL https://api.diffraction.sh/cli | bash
diffraction --version
diffraction help
```
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:
```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
curl -fsSL https://api.diffraction.sh/cli | bash -s -- --prefix "$HOME/tools/diffraction"
```
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
```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
diffraction login
```
Choose **Read only** (default) or **Read & write**, or set it explicitly:
```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
diffraction login --access read-write
```
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.
```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
diffraction repositories
diffraction reviews --repo
diffraction review
diffraction status --watch --timeout 600
diffraction steps --target
diffraction comments
diffraction insights
diffraction evidence
diffraction evidence --artifact --output ./capture.png
```
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:
```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
diffraction review-pr 42 --repo
diffraction review-commit --repo
```
The CLI prints a request key. Reuse it with `--request-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:
```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
diffraction review-local --directory ../your-web-app --dry-run --json
```
Tracked working-tree files are included subject to exclusions. Select each wanted
untracked file with `--include`:
```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
diffraction review-local --directory ../your-web-app --dry-run --json --include src/new-page.tsx
diffraction review-local --directory ../your-web-app --repo --include src/new-page.tsx
```
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](/docs/site/evidence#local-source-uploads).
## Context and rules
```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
diffraction context get
diffraction context put ./product-context.md --title "Product context"
diffraction context get --repo
diffraction context put ./repository-context.md --repo
diffraction company-rules get
diffraction company-rules put ./rules.json --version
```
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
| Code | Meaning |
| ---- | -------------------------------------------------------- |
| 1 | Input, connection, or operation failure. |
| 2 | Sign-in or consent required. |
| 3 | Access denied. |
| 4 | Status watch timed out; the review may still be running. |
| 5 | Watched review ended failed, cancelled, or superseded. |
JSON failures include a stable error code. Inspect findings, execution, and delivery
status before interpreting a terminal failure. For another configured deployment,
`--config ` accepts `resource`, `issuer`, and `clientId`; non-secret server
configuration belongs in that file, not environment variables.