# Setup and recovery

The canonical CLI installation guide is [betterfilings.com/cli/setup](https://betterfilings.com/cli/setup). Read it before installing or updating; it contains the current pinned package and optional processor commands.

After setup:

1. Run `betterfilings doctor --json` to check the CLI and optional local processor.
2. Run `betterfilings setup --json` for the exact optional processor plan. This command prints instructions and never installs software.
3. Authenticate with `betterfilings auth request --email ADDRESS`, then pass the emailed code to `betterfilings auth verify --otp-stdin` through stdin. Keep the same `--host URL` on both commands when using a non-default origin.
4. Verify access with `betterfilings usage --json`.

## Offline recovery

If the package is already installed, stay offline and inspect before changing anything: run `betterfilings doctor --json`, `betterfilings setup --json`, and `betterfilings --help`. Reuse the existing installation and credential origin. The setup output identifies missing optional files without downloading or installing them. Do not log email codes, tokens, cookies, passwords, or credential-file contents.

Search and downloads do not require Python. Local HTML, PDF, and XBRL processing does. Do not edit system Python or package source. Windows local processing is unsupported; use hosted MCP or a verified macOS arm64/Linux x64 environment.

When connectivity returns, run `betterfilings auth status --json` to verify authentication and `betterfilings update --check --json` to check the package. If an update is available, use its exact command while reusing the dedicated Bun package, bin, and cache directories from [the canonical setup guide](https://betterfilings.com/cli/setup). Do not run an unconfigured global install.

For hosted MCP, connect `https://betterfilings.com/mcp` in the client and call `research_help`. MCP does not require the local processor.