Skip to main content
Version: MVP

Installation

3 min readFor everyoneUpdated 2026-05-19

What you'll do

Install the Craik CLI on a workstation or CI runner, verify it runs, and prepare the local state directory. After this guide you'll have craik on your PATH and ~/.craik ready to hold projects, receipts, handoffs, and case files.

1 · Check your prerequisites​

Craik is a Python CLI. You need a recent Python interpreter and a way to put the CLI on your PATH.

Python ≥ 3.12

3.12, 3.13, or 3.14. Verify with python3 --version.

pip or pipx

pipx is recommended for an isolated CLI install; pip works for project-local installs.

Git (optional but expected)

Craik registers Git repositories as projects. Without Git you can still install Craik but the project workflows will be limited.

If python3 --version reports 3.11.x or older, install a newer interpreter first — pyenv, uv python install 3.12, brew install [email protected], or your distro package manager all work.

2 · Pick an install method​

Use pipx (recommended)

  • You want a standalone craik command available everywhere.
  • You don't want Craik mixed into a project's virtualenv.
  • You'll keep one global version and upgrade with pipx upgrade.

Use pip in a venv

  • You're integrating Craik into a project's own Python environment.
  • You're packaging Craik into a CI image with pinned dependencies.
  • You're a contributor working from a local checkout.

Install with pipx​

Install Craik as an isolated CLI
pipx install craik
craik --version

If pipx isn't on your machine yet:

Install pipx, then Craik
python3 -m pip install --user pipx
python3 -m pipx ensurepath
# Open a new shell, then:
pipx install craik

Install with pip​

Install into the current Python environment
python3 -m pip install craik
craik --version

Install from a local checkout (contributors)​

Editable install with dev extras
git clone https://github.com/eidetic-labs/craik.git
cd craik
python3 -m pip install -e ".[dev]"
craik --version

For reproducible source-tree commands, uv is fully supported:

Source-tree commands with uv
uv run --python 3.12 --extra dev craik --version

3 · Verify the install​

Confirm the CLI is on your PATH and responsive
craik --version
craik --help

You should see a semantic version (for example, 0.1.x) and the subcommand list. If craik is not found, pipx ensurepath (or activating your venv) usually resolves it.

4 · Initialize local state​

Craik stores project state, receipts, handoffs, and case files under a single home directory:

craik home init

Creates ~/.craik/ and the per-data-class subdirectories Craik writes to during a run.

If you want Craik to store state somewhere else, point CRAIK_HOME at any directory you control before running anything:

Use a custom CRAIK_HOME
export CRAIK_HOME="$HOME/work/craik-home"
craik home init

The Craik home layout looks like this once initialized:

~/.craik/
  config/      # user-level config and credential profile definitions
  secrets/     # secret material (never committed)
  state/       # SQLite store: projects, tasks, receipts, handoffs, case files
  cache/       # short-lived caches
  logs/        # diagnostic logs
  receipts/    # exported receipts
  handoffs/    # exported handoffs
  case-files/  # exported case files
  projects/    # per-project artifacts and exports

See Configuring Craik home for relocation rules, multi-host shares, and CI conventions.

5 · (Optional) Authenticate as an operator​

Fixture-backed provider execution works without any credentials, so you can explore Craik end-to-end before connecting a real model. When you're ready for live provider calls:

Operator identity + first credential profile
craik login
craik auth add anthropic:work --kind=api-key --env-var=ANTHROPIC_API_KEY
craik auth status

The full reference — OIDC device-code and loopback flows, credential pools, workload identity, secret-manager integrations — lives in Authentication and credentials.

tip

The "live providers cost money" reflex is correct. Craik never makes a live provider call without you opting in: you supply provider metadata, the policy envelope must allow live access, and a credential profile must be bound to the run. Until you do all three, the fixture path is what runs.

Troubleshooting​

craik: command not found

Run pipx ensurepath and open a new shell. If you used pip, confirm the install location with python3 -m pip show -f craik and add the script directory to PATH.

Python 3.11 is too old

Install a 3.12+ interpreter and re-run the install. With pipx: pipx install --python python3.12 craik.

ModuleNotFoundError: craik

You're likely in the wrong venv. Activate the environment where you installed Craik or run via the absolute install path.

Behind a proxy / offline mirror

Pip and pipx both honor PIP_INDEX_URL. For air-gapped installs, pre-build a wheel with pip wheel craik on a connected host and copy.

What's next​

Step 2QuickstartRegister a project, build a case file, run a governed task.Step 3Run the setup wizardAn interactive walkthrough that wires together home, identity, and a first project.ConceptRead the runtime modelUnderstand the typed objects Craik composes — project, case file, receipt, handoff.