Skip to main content
Version: MVP

Config reference

3 min readReferenceUpdated 2026-05-19

What you'll find here

How Craik v0.1.0 is configured — environment variables, the local home, the setup / doctor / update commands, project-level context discovery rules, Stigmem and GitHub env vars, and pre-publication validation.

Env-var-driven, with a structured local home.

Configuration lives in the environment and in CRAIK_HOME. Project-local .craik/ directories are opt-in only.

Local state​

Variable
Default
Purpose
CRAIK_HOME
~/.craik
Overrides the default state directory.

Craik stores runtime state in a SQLite database under CRAIK_HOME/state/. Project-local .craik/ directories are opt-in only and are not created by the current CLI.

Setup commands​

Command
Mutates?
Notes
craik setup
yes
Creates the local home layout, initializes the local store, writes a default craik.gateway_config. Prints secrets_written = false and does not collect API keys, channel tokens, webhook secrets, or bearer credentials.
craik doctor
no
Reports pass / warning / failure diagnostics for local home, local store, memory backend, gateway prerequisites, and gateway policy readiness. Does not create files or contact external services.
craik update
no
Read-only update guidance — installed version, supported Python range, contract compatibility, local-store migration compatibility, manual update steps, and non-mutating boundaries. Does not fetch release metadata, rewrite the install, or migrate local state.

Context discovery​

Project profiles can store documentation discovery overrides through craik project add.

Option
Scope
Purpose
--discovery-exclude <glob>
project
Adds a project-level context exclusion rule.
--discovery-include <glob>
project
Adds a project-level include rule that can restore a default-excluded path.

craik case build accepts the same options as one-off user overrides for a single case-file build. Craik always starts from conservative defaults that skip generated, dependency, build, cache, and archive-heavy paths. The resulting case file records active rules and skipped paths in context_budget.

Stigmem​

Variable
Default
Purpose
CRAIK_STIGMEM_URL
unset
Base URL for the Stigmem node.
CRAIK_STIGMEM_API_KEY
unset
Bearer token for authenticated Stigmem nodes.
CRAIK_STIGMEM_TIMEOUT
5.0
Request timeout in seconds.

Never commit API keys.

Craik redacts token-shaped values from persisted payloads and command output, but the discipline starts with you.

GitHub​

Variable
Default
Purpose
CRAIK_GITHUB_TOKEN
unset
Preferred bearer token for GitHub API reads.
GITHUB_TOKEN
unset
Fallback bearer token.
CRAIK_GITHUB_API_URL
https://api.github.com
GitHub API base URL.
CRAIK_GITHUB_TIMEOUT
5.0
Request timeout in seconds.

The GitHub adapter is read-only in v0.1.0.

Validation​

Run before publishing changes:

uv run --python 3.12 --extra dev ruff check .
uv run --python 3.12 --extra dev mypy
uv run --python 3.12 --extra dev pytest
uv run --python 3.12 --extra dev craik policy test

What's next​

ReferenceCLIThe auto-generated command reference.GuideConfiguring Craik homeRelocation rules, multi-host shares, and CI conventions.GuideDevelopment checksPre-publication validation in detail.