> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whyfile.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install whyfile, pick an LLM backend, and understand the graphify runtime dependency.

## Requirements

`whyfile` post-processes graphify graphs and depends on `graphifyy` (the `graphify` runtime that every backend calls), which is installed automatically (ADR-0010). By default it uses your **Claude Pro/Max subscription** via the Claude Code CLI, so **no API key is required**. To use a billed API key instead, see [LLM backend](#llm-backend).

## Installation

```bash theme={null}
pip install whyfile          # brings graphifyy (the graphify runtime) with it
# or as a standalone tool:
uv tool install whyfile
```

Not a Python project? `whyfile` is a standalone dev tool — install it the way you install your other CLIs:

| You have…           | Install with                                                                                                                                                          |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uv`                | `uvx whyfile` — or `uv tool install whyfile` to put it on PATH                                                                                                        |
| `npm` / Node        | `npx whyfile` — delegates to `uv`; if `uv` is missing it prints the one-line install                                                                                  |
| neither / no Python | install `uv` (`curl -LsSf https://astral.sh/uv/install.sh \| sh`, `brew install uv`, or `winget install astral-sh.uv`), then `uvx whyfile` — uv brings its own Python |

The LLM backend still needs the `claude` CLI (subscription default) or an API key — see [LLM backend](#llm-backend).

For an **API** backend, add the provider extra so graphify has its SDK (the subscription backend needs neither):

```bash theme={null}
pip install 'whyfile[anthropic]'   # Anthropic API
pip install 'whyfile[gemini]'      # Gemini API
```

To enable Pass D's embedding-based concept resolution, add the optional extra:

```bash theme={null}
pip install whyfile[embeddings]   # local model2vec embedder for Pass D
```

Without it, Pass D still runs, degrading gracefully to a lexical-similarity fallback.

## LLM backend

By default, `whyfile` uses your **Claude Pro/Max subscription** through the
[Claude Code CLI](https://docs.claude.com/en/docs/claude-code) (`claude`): no API key,
no per-token billing (the run still counts against your plan's usage limits; see
[What a run costs](caching-and-cost.md#what-a-run-costs)). It falls back to a billed API key if the CLI isn't
available.

| `--backend`             | Behaviour                                                                       |
| ----------------------- | ------------------------------------------------------------------------------- |
| *(unset)*               | **Subscription** if the `claude` CLI is on your `PATH`, else a detected API key |
| `subscription`          | Force the Claude Code CLI (subscription auth)                                   |
| `api`                   | Force a billed API key (`ANTHROPIC_API_KEY` / `GEMINI_API_KEY`)                 |
| `claude` / `gemini` / … | Force a specific graphify backend                                               |

You can also set `GRAPHIFY_INTENT_BACKEND`. For subscription mode, install the `claude`
CLI and run it once to sign in. For API mode, install the matching extra
(`graphifyy[anthropic]` or `graphifyy[gemini]`) and provide the key.

### Keep API keys out of `.env` and your shell history

If you do use an API key, prefer a password-manager CLI over inlining the secret. With
[1Password's `op`](https://developer.1password.com/docs/cli/), inject it at runtime so it
never lands on disk in plaintext:

```bash theme={null}
export ANTHROPIC_API_KEY="$(op read 'op://<vault>/<item>/credential')"
whyfile --backend api --graph graphify-out/graph.json --docs docs/
```

…or wrap the command with `op run` so the secret lives only for that process:

```bash theme={null}
op run --env-file=.env.op -- whyfile --backend api --graph graphify-out/graph.json --docs docs/
```

A real key committed in `.env` risks leaking into git history, CI logs, and backups; a
manager keeps it encrypted, access-audited, and revocable. Best of all, the default
subscription backend needs no key at all.

## graphify runtime dependency

Every backend routes through graphify's `graphify.llm`, so `whyfile` declares `graphifyy` as a **runtime dependency**; `pip install whyfile` installs it (ADR-0010). For an API backend, add the provider extra so graphify's SDK is present:

```bash theme={null}
pip install 'whyfile[anthropic]'   # --backend api with Anthropic
pip install 'whyfile[gemini]'      # --backend api with Gemini
```

The default subscription backend needs no provider SDK, only the [Claude Code CLI](https://docs.claude.com/en/docs/claude-code) (`claude`), installed and signed in. If the graphify runtime is somehow missing, `whyfile` exits immediately with a clear install message rather than failing deep inside a run.