Skip to main content

​
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.

​
Installation

Not a Python project? whyfile is a standalone dev tool — install it the way you install your other CLIs:
You have…Install with
uvuvx whyfile — or uv tool install whyfile to put it on PATH
npm / Nodenpx whyfile — delegates to uv; if uv is missing it prints the one-line install
neither / no Pythoninstall 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. For an API backend, add the provider extra so graphify has its SDK (the subscription backend needs neither):
To enable Pass D’s embedding-based concept resolution, add the optional extra:
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 (claude): no API key, no per-token billing (the run still counts against your plan’s usage limits; see What a run costs). It falls back to a billed API key if the CLI isn’t available.
--backendBehaviour
(unset)Subscription if the claude CLI is on your PATH, else a detected API key
subscriptionForce the Claude Code CLI (subscription auth)
apiForce 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, inject it at runtime so it never lands on disk in plaintext:
…or wrap the command with op run so the secret lives only for that process:
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:
The default subscription backend needs no provider SDK, only the Claude Code CLI (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.