# Better Filings: installation for shell agents

Use these instructions when the user asks you to install or use Better Filings. Follow your environment's permission rules. That request authorizes the necessary user-local setup; ask only when the environment requires approval or a new action needs it. Never use administrator privileges or alter unrelated software.

Workflow guides: https://betterfilings.com/agents. After installing a CLI that includes guides, run `betterfilings guide list` for offline workflow and recovery instructions.

## 1. Inspect before installing

Identify the OS and shell. Check whether Bun and betterfilings are available, and reuse a working installation. Use a dedicated user-local installation. This is one JavaScript package running under Bun; Bun itself supplies the platform runtime.

If Bun is missing, read https://bun.com/docs/installation and follow its official instructions for the detected platform. Bun 1.3.14 or newer is required. Do not download from an unofficial mirror. Ensure Bun's executable directory is in the current shell PATH; explain persistent shell edits if needed.

## 2. Install and verify the CLI

Pin Bun's package, binary and cache directories before installing. Do not rely on a global default or HOME alone, especially in an isolated agent environment. Keep these variables for every install/update invocation. Choose paths inside the authorized user home. Initialize the dedicated directory with its own package.json before the first installation, as shown below. This prevents Bun from selecting an ancestor project. Preserve an existing manifest; never overwrite one.

macOS/Linux (sh, bash or zsh):

```sh
export BUN_INSTALL_GLOBAL_DIR="$HOME/.local/share/betterfilings/cli"
export BUN_INSTALL_BIN="$HOME/.local/bin"
export BUN_INSTALL_CACHE_DIR="$HOME/.cache/betterfilings/bun"
export PATH="$BUN_INSTALL_BIN:$PATH"
mkdir -p "$BUN_INSTALL_GLOBAL_DIR"
if [ ! -f "$BUN_INSTALL_GLOBAL_DIR/package.json" ]; then
  printf '%s' '{"private":true}' > "$BUN_INSTALL_GLOBAL_DIR/package.json"
fi
bun add --global @betterfilings/cli@https://downloads.betterfilings.com/cli/packages/0.2.4/betterfilings-cli-0.2.4.tgz
betterfilings doctor --json
betterfilings --help
```

Windows PowerShell installation recipe (not yet acceptance-tested; local Python processing remains unsupported):

```powershell
$env:BUN_INSTALL_GLOBAL_DIR = Join-Path $env:LOCALAPPDATA "BetterFilings/cli"
$env:BUN_INSTALL_BIN = Join-Path $env:LOCALAPPDATA "BetterFilings/bin"
$env:BUN_INSTALL_CACHE_DIR = Join-Path $env:LOCALAPPDATA "BetterFilings/cache/bun"
$env:PATH = "$env:BUN_INSTALL_BIN;$env:PATH"
New-Item -ItemType Directory -Force -Path $env:BUN_INSTALL_GLOBAL_DIR | Out-Null
$bfManifest = Join-Path $env:BUN_INSTALL_GLOBAL_DIR "package.json"
if (-not (Test-Path $bfManifest)) { '{"private":true}' | Set-Content -Encoding utf8 $bfManifest }
bun add --global @betterfilings/cli@https://downloads.betterfilings.com/cli/packages/0.2.4/betterfilings-cli-0.2.4.tgz
betterfilings doctor --json
```

Before running processor setup, confirm the doctor result's package root is inside the selected CLI directory. If it is outside the authorized home, stop and report the unexpected location. Do not follow that path or change unrelated files. The global directories are documented at https://bun.com/docs/runtime/bunfig .

If the command is unavailable, use the executable directory printed by the installation and check the current PATH. You can also try `bun pm bin -g`; if that diagnostic fails, use the installation output instead. Use the installed executable's absolute path or add that directory to the current shell PATH. Do not install a second copy merely because PATH is missing.

Always include the @betterfilings/cli@ prefix shown in the command when installing or updating; using only the tarball URL can leave a stale package entry in Bun's lockfile.

The package is hosted directly by Better Filings, not currently published to the npm registry. There are no install hooks or automatic Python dependency installations. Search, account commands and downloads work without Python. Doctor can report optional processor setup as required while the CLI itself works.

## 3. Authenticate only for service-backed work

Local files can be processed without an account. To search filings or use managed downloads, first check `betterfilings auth status --host https://betterfilings.com`. If unauthenticated, get the user's account email and run:

```sh
betterfilings auth request --email ADDRESS --host https://betterfilings.com
betterfilings auth verify --otp-stdin --host https://betterfilings.com
```

Pass the short-lived emailed code to the second command through stdin. Never put it in a command argument, saved script or log. Only the user completes email verification; do not invent a code or borrow credentials from another account. Follow a returned signup-disabled error; a new installation does not create an account automatically. Existing accounts can sign in while signup is closed.

Verify with `betterfilings usage --json --host https://betterfilings.com`, then start with `betterfilings company search Apple --json --host https://betterfilings.com`. Retain returned listing IDs and follow the CLI help for filing search/get/download. Use `--input` for complex JSON requests. Credentials belong in the CLI's credential store, never the parser environment.

## 4. Set up optional document tools only when needed

For local HTML/PDF/XBRL processing, run:

```sh
betterfilings setup --json
```

This prints a plan; it does not install anything. Use the exact commands and absolute paths returned by this installed release. They create a dedicated Python 3.12 environment, install the bundled hash-locked binary requirements, then install the bundled Better Filings processor wheel without resolving extra dependencies.

If uv is missing, use its official installation instructions at https://docs.astral.sh/uv/getting-started/installation/ for a user-local installation. Execute the plan only within the user's authorized setup. Never modify system Python, substitute dependency versions, bypass hashes/TLS checks, or compile from source to force an unsupported platform to work.

Local processing is verified on macOS ARM64 and Linux x64. Windows local processing is currently unsupported; do not patch the installed package to make it work. Windows CLI operation is not yet acceptance-tested. Bun portability is not a claim that every Python dependency or processor feature works everywhere.

XBRL processing may need network access to fetch allowlisted public taxonomy files, even after Python setup is complete. If a full filing package returns missing_taxonomies, check the execution environment's network permission and connectivity before reinstalling dependencies. Request normal network permission when needed; never disable TLS verification or bypass an access block.

After installation, run the plan's verification command and `betterfilings doctor --json`. Verify a real operation on the user's selected filing before declaring the document tools ready. Missing Python affects local processing only; do not silently switch to billable hosted processing.

## 5. Read filings efficiently

Download source files to disk. Do not paste whole filings into context. Use `document inspect` to understand available pages/sections and `document search` to locate passages. Then extract a bounded range:

```sh
betterfilings document search --file report.html --queries liquidity --json
betterfilings document extract --file report.html --text --text-offset 0 --text-limit 2000 --json
betterfilings document extract --file report.pdf --pages 12 --text-limit 2000 --json
betterfilings document render --file report.pdf --page 12 --output page-12.png --json
betterfilings xbrl search --file filing.zip --queries revenue --json
```

For exact reported data, use an available full XBRL package and discover concepts with `xbrl search` before `xbrl query`. Standalone inline HTML may lack required relative schemas. Preserve concepts, periods, units and dimensional scopes. Follow returned continuation offsets exactly. Section detection is best-effort; this is not a table reconstruction or OCR tool. Keep filing URLs, source hashes and page/text/fact locators in your answer.

## 6. Recover and update

Diagnose the concrete failure with doctor, setup output and command diagnostics. Common recoverable issues are PATH, a missing supported Python runtime, an interrupted download, or permissions in the dedicated environment. Retry after correcting the identified cause. Never change unrelated environments, weaken verification, or evade source-site access blocks.

Run `betterfilings update --check --json --host https://betterfilings.com` for the current package installation command. Reuse the explicit BUN_INSTALL_GLOBAL_DIR, BUN_INSTALL_BIN and BUN_INSTALL_CACHE_DIR from installation when executing that command; do not use an unconfigured global install. Updates are explicit through Bun; the CLI never updates in the background. After an update, check doctor again and follow the new release's optional processor plan if needed.

For `quota_exceeded`, report the returned reset time and account-management path; do not repeatedly retry. Failed, unavailable, unsupported, access-denied and empty results are distinct. If a dependency or platform is unsupported, report the exact blocker and continue tasks that do work.

MCP-only clients should use https://betterfilings.com/connect. The separate install.mjs helper installs an MCP connection, not this CLI. Further workflow guidance: https://betterfilings.com/agent-skill and https://betterfilings.com/docs.