# CLI

> The `crawrix` binary mirrors the web product: audits, findings, GEO readiness, and optional GitHub PRs — with diffs on an approval card before anything writes to disk.

## Install

Node.js 20 or later. The binary is always named `crawrix`.

npm / pnpm / bun:

```bash
npm i -g crawrix
# or
pnpm add -g crawrix
# or
bun add -g crawrix

crawrix --version
crawrix --help
```

One-shot without a global install:

```bash
npx crawrix audit --json
```

## Authenticate

Three paths — pick one:

- **Hosted** (recommended with a crawrix account) — no provider key to manage. Model calls route through your account.
- **BYOK via Vercel AI Gateway** — one key, full `provider/model` catalogue.
- **BYOK direct** — Anthropic or OpenAI key for that provider's models only.

Hosted device flow:

```bash
crawrix login --hosted
# Approve the code in the browser while signed in
crawrix whoami
```

BYOK:

```bash
crawrix login --provider anthropic   # pastes sk-ant-…
crawrix login --provider openai      # pastes sk-…
crawrix login --provider gateway     # Vercel AI Gateway key
```

> **Where keys live.** Credentials go in `~/.crawrix/config.json` (mode `0600`). The local `.crawrix/` workspace is safe to commit — never put secrets there.

## First audit

1. **Enter a repo.** Any modern JS framework works (Next.js, Astro, SvelteKit, Remix, Nuxt, and more). Detection is automatic — no flag needed.

   ```bash
   cd ~/code/my-nextjs-app
   ```

2. **Initialize the workspace.** Creates `.crawrix/` for audits, findings, and reports, and adds it to `.gitignore`.

   ```bash
   crawrix init
   ```

3. **Open the REPL or run a one-shot audit.**

   Interactive:

   ```bash
   crawrix
   # then: audit this repo for SEO issues
   ```

   Non-interactive / CI:

   ```bash
   crawrix audit --json
   ```

## Approvals

Write tools — edit, write, delete, and open PR — pause for approval. The diff on the card is display-only; the tool re-reads the file on execute so a mid-flight change fails loudly instead of applying stale content.

- **Normal mode** — you approve each write.
- **Auto mode** — auto-approves safe file edits; deletes and PRs still need a human.
- **Plan mode** — research only; every write is declined.

Cycle modes with `shift+tab`, or `/plan` / `/auto`. `--yes` raises the risk ceiling for unattended runs; it never opens a PR without a TTY.

## Useful commands

| Command | What it does |
| --- | --- |
| `crawrix` | Interactive REPL (requires a TTY). |
| `crawrix audit` | Non-interactive audit; add --json for machines. |
| `crawrix findings list` | Index of findings, severity-sorted. |
| `crawrix whoami` | Show the signed-in identity / key slots. |
| `crawrix sync` | Push local artefacts to the hosted dashboard. |
| `crawrix login --hosted` | Device-flow login to your account. |

> **Sync to the dashboard.** With hosted auth, `crawrix sync` pushes local audits and findings into the web app. For CI, export `CRAWRIX_TOKEN` instead of shipping a provider key. Prefer the [MCP server](https://crawrix.ai/docs/mcp) when you want the same outcomes from Claude Code or Cursor.
