CLI reference
heddle init
Shippedheddle init [OPTIONS] [PATH] Initialize Heddle in a directory or existing Git checkout. Auto-detects a .git directory: beside Git you get Git Overlay; in an empty directory you get a standalone Heddle repository. No flag toggles between them — what is on disk decides.
Output text (default) · json
heddle init writes the .heddle directory at the target path. It never modifies .git; the overlay is additive, and removing .heddle leaves Git working exactly as before. Moving source authority to Heddle is a separate, one-way command — heddle adopt.
Principal identity can be set here with --principal-name and --principal-email. If omitted, Heddle resolves it later, highest first: the HEDDLE_PRINCIPAL_NAME / HEDDLE_PRINCIPAL_EMAIL environment variables, repository config, Git config, user config, then Unknown .
On first init, Heddle may offer to install harness integrations for the host. Automation should pass --no-harness-install. Install a specific set non-interactively with --install-harnesses; choose where with --harness-install-scope repo (the default) or user, which also accepts the shorter --scope spelling.
init does not write a .heddleignore. Heddle auto-ignores only .heddle itself — everything else you want excluded must be named, and only the two root-level ignore files are evaluated.
Arguments
[PATH]path optional- Directory to initialize. default:
current directory
Flags
--principal-name <name>- Principal name for attribution.
--principal-email <email>- Principal email for attribution.
--install-harnesses <names>- Install harness integrations after init.
--no-harness-install- Skip harness integration installation during init. Pass this in automation.
--harness-install-scope <scope>- Preferred install scope, repo or user. Accepted alias: --scope. default:
repo --harness-install-force- Overwrite Heddle-managed integration entries when needed.
Exit codes
Declared by this command's contract, verbatim. Anything not listed
contracts only to 0 on success and an unspecified
non-zero on failure. The full table
and the retry rule — in short, 75 is the only code that
is safe to retry.
0- ok
73- cannot create state directory
78- workspace config invalid
Examples
Onboard an existing Git repo (non-destructive sidecar)
bash$ cd my-repo$ heddle init --no-harness-install# existing Git becomes Git Overlay; .git is untouchedInitialise standalone (no Git)
bash$ mkdir new-project && cd new-project$ heddle init --principal-name 'Ada Lovelace' --principal-email ada@example.com