# CLI Reference

Core commands:

- `version`
- `init-project`
- `scan-project`
- `build-index`
- `search-context`
- `get-context-pack`
- `context-status`
- `why-file`
- `self-test`
- `mcp-server`
- `mcp-server --storage-profile native-archive`
- `mcp-client-smoke`
- `mcp-config-template`
- `mcp-config-validate`
- `context-commit`
- `context-log`
- `context-diff`
- `git-status`
- `context-push`
- `context-pull`
- `run-mcp8-hardening`
- `import-native-ithz`
- `native-ithz-status`
- `native-ithz-context-pack`
- `init-minimal-memory`
- `audit-markdown-memory`
- `suggest-markdown-reduction`
- `context-store-status`
- `migrate-store-name`
- `run-context-compiler-benchmark`
- `run-context-quality-regression`
- `prompt-memory-status`
- `record-prompt-response`
- `prompt-log`
- `prompt-search`
- `prompt-context-pack`
- `plan-markdown-migration`
- `apply-markdown-migration`
- `write-bootstrap-files`
- `run-mcp9f-native-ithz`
- `run-mcp10-markdown-minimal`
- `run-mcp11-external-client`
- `run-mcp12-prompt-memory`
- `init-native-archive-memory`
- `archive-memory-status`
- `archive-search-context`
- `archive-get-context-pack`
- `archive-record-prompt-response`
- `archive-ingest-project-memory`
- `archive-finalize-task`
- `archive-adopt-project-workflow`
- `workflow-ingest-prompt`
- `workflow-profile-status`
- `workflow-context-pack`
- `agent-history-discover`
- `archive-import-agent-history`
- `archive-link-zone`
- `archive-zone-status`
- `archive-cross-zone-context-pack`
- `archive-record-cross-zone-event`
- `archive-append-event`
- `archive-memory-index-status`
- `archive-rebuild-derived-indexes`
- `archive-create-snapshot`
- `ithz-add-claim`
- `ithz-block-claim`
- `ithz-can-i-claim`
- `ithz-add-reviewer-note`
- `ithz-create-replication-pack-record`
- `ithz-get-project-ledger-summary`
- `git-diff-ithz`
- `git-merge-ithz`
- `install-git-drivers`
- `git-driver-status`
- `run-mcp16-git-merge-driver`
- `run-mcp17-append-index-snapshot`
- `run-mcp13-host-compat`
- `write-host-installers`
- `run-mcp21-production-readiness`
- `run-mcp25-macos-package`
- `run-mcp26-memory-synthesis`
- `run-mcp27-project-ledger`
- `run-mcp28-ubuntu-package`
- `run-mcp29-memory-effectiveness`
- `run-production-readiness`

Native archive memory commands:

```powershell
python -m ithz_mcp init-native-archive-memory --project <project>
python -m ithz_mcp archive-memory-status --project <project>
python -m ithz_mcp archive-search-context --project <project> --query "decision gate risk"
python -m ithz_mcp archive-get-context-pack --project <project> --query "next task" --out native_pack.md
python -m ithz_mcp archive-record-prompt-response --project <project> --prompt prompt.md --response response.md --task "task" --mode summary
python -m ithz_mcp archive-ingest-project-memory --project <project> --source AI_PROJECT_BRIEF.md --source WORKFLOW_RULES.md
python -m ithz_mcp archive-finalize-task --project <project> --task "task" --summary task_summary.md --docs-impact updated --memory-impact handoff-created --gate "Gate: run-ci-fast passed"
python -m ithz_mcp archive-adopt-project-workflow --project <project> --profile gobi --owner Gobi --prompt C:\work\tmp\new_project_prompt.txt
python -m ithz_mcp workflow-ingest-prompt --project <project> --profile gobi --prompt workflow_update.md
python -m ithz_mcp workflow-profile-status --project <project>
python -m ithz_mcp workflow-context-pack --project <project> --profile gobi --query "test workflow"
python -m ithz_mcp agent-history-discover --project <project> --source codex --author Gobi
python -m ithz_mcp archive-import-agent-history --project <project> --source codex --author Gobi --apply
python -m ithz_mcp write-host-installers --project <project> --out host_installers
python -m ithz_mcp write-host-installers --project <project> --out host_installers_macos --launcher /path/to/ithz_mcp_server.sh --storage-profile legacy
python -m ithz_mcp archive-link-zone --project <project> --zone native_ithz --path C:\work\ITHKOR\native_ithz
python -m ithz_mcp archive-zone-status --project <project>
python -m ithz_mcp archive-cross-zone-context-pack --project <project> --query "native update-files API" --out cross_zone_pack.md
python -m ithz_mcp archive-record-cross-zone-event --project <project> --target-zone native_ithz --event "MCP task touched native transport API"
python -m ithz_mcp mcp-server --project <project> --mode read-only --protocol mcp --storage-profile native-archive
```

Memory-zone options:

- default: `--memory-zone nearest`, so the nearest `project.ithz` from `--project` upward is the active memory zone;
- `--memory-zone current` forces `<project>\project.ithz`;
- `--memory-zone parent` selects the nearest parent archive above the active nested zone;
- `--memory-zone-path <dir-or-project.ithz>` selects an explicit parent, sibling or manual archive zone;
- `init-native-archive-memory --include-child-zones` is the only mode that intentionally snapshots nested child-zone content into a parent archive.

```powershell
python -m ithz_mcp archive-memory-status --project <subproject>
python -m ithz_mcp archive-search-context --project <subproject> --memory-zone parent --query "repo gates"
python -m ithz_mcp archive-get-context-pack --project <subproject> --memory-zone-path <sibling> --query "shared decision"
python -m ithz_mcp archive-record-prompt-response --project <subproject> --memory-zone parent --prompt prompt.md --response response.md --task "parent note"
```

Cross-zone registry:

- `archive-link-zone` records a parent, child, sibling or external zone in `zones/linked_zones.json` inside the active `project.ithz`.
- `archive-zone-status` reports detected zones plus explicit linked zones and cross-zone event count.
- `archive-cross-zone-context-pack` reads the active zone and linked zones to build one deterministic pack.
- `archive-record-cross-zone-event` records a project-memory event in `zones/cross_zone_events.jsonl`, for example when one task modifies both `ithz_mcp` and sibling `native_ithz`.
- Cross-zone writes remain explicit CLI operations; read-only MCP host tools expose zone status and cross-zone packs, not write tools.

Append-only memory/index/snapshot commands:

```powershell
python -m ithz_mcp archive-append-event --project <project> --kind decision --text "Decision: keep p9-v4 experimental." --source "sprint"
python -m ithz_mcp archive-append-event --project <project> --kind gate --text "Gate: run-ci-fast passed." --source "sprint" --include-git
python -m ithz_mcp archive-memory-index-status --project <project>
python -m ithz_mcp archive-rebuild-derived-indexes --project <project>
python -m ithz_mcp archive-compile-memory-synthesis --project <project>
python -m ithz_mcp archive-create-snapshot --project <project> --label "after sprint" --mode auto
```

Native context packs are ordered for agent use: selected evidence first, candidate files and evidence gaps next, then task-relevant current-memory synthesis. If a query has weak/no exact coverage, the pack says so instead of presenting broad memory as sufficient evidence. File-navigation queries prefer concrete source file summaries and skip broad current-memory synthesis; platform-sensitive queries such as Ubuntu/Linux versus Windows avoid ranking opposite-platform installer evidence first.

- `archive-append-event` adds immutable audit events to `events/events.jsonl` and refreshes `indexes/current_index.json` plus `indexes/memory_synthesis.json`.
- `archive-append-event --include-git` stores read-only Git metadata on that event, including branch, full hash, short hash and current commit subject/title. It does not stage, commit, push, reset or checkout anything.
- `archive-memory-index-status` verifies that the stored current index and memory synthesis match a deterministic rebuild from the append-only events.
- `archive-rebuild-derived-indexes` recreates derived indexes from the append-only event log.
- `archive-compile-memory-synthesis` refreshes only the deterministic current working-memory view.
- `archive-create-snapshot --mode auto` writes a compact point-in-time summary for small archives and returns `snapshot_deferred` for large archives instead of forcing a slow rewrite.
- Search and context-pack commands include the current index and memory synthesis, so appended decisions/gates/risks and stale/superseded notes are discoverable without scanning the whole raw history.

Durable instruction commands:

```powershell
python -m ithz_mcp durable-instruction-status --project <project>
python -m ithz_mcp record-workflow-rule --project <project> --profile gobi --text "After completed durable tasks, run tests, commit, and deploy through SSH."
python -m ithz_mcp record-project-decision --project <project> --profile gobi --text "Decision: use SSH deploy as the project deployment workflow."
python -m ithz_mcp record-gate-rule --project <project> --profile gobi --text "Gate: run tests and confirm no secrets are staged before commit."
python -m ithz_mcp record-risk-rule --project <project> --profile gobi --text "Risk: never store SSH private keys, API tokens, passwords or deployment secrets."
python -m ithz_mcp ingest-user-instruction --project <project> --profile gobi --text "Po dokonceni tasku commitni. Pred commitom spusti testy. Neskladuj SSH kluce."
```

- Durable instruction commands write typed workflow, decision, gate and risk records under `instructions/` inside `project.ithz`.
- The same records are mirrored into append-only events so search and context packs can retrieve them.
- Secret-like instruction text is blocked before storage.
- Read-only MCP profiles do not expose these write tools.

`archive-record-prompt-response` stores summary-mode prompt memory through `ithz-native --update-files ... --input -`: it updates `prompts/prompt_log.jsonl` and `manifest.json` inside `project.ithz` in one archive rewrite, without extracting a restored tree to disk. The archive file is still rewritten safely; it is not an in-place database mutation.

End-of-task checkpoint commands:

```powershell
python -m ithz_mcp install-project --apply
python -m ithz_mcp install-project --apply --agent-intake auto
python -m ithz_mcp agent-intake-project --project . --mode codex-cli
python -m ithz_mcp archive-ingest-project-memory --project . --source AI_PROJECT_BRIEF.md --source WORKFLOW_RULES.md --source DECISIONS_LOG.md
python -m ithz_mcp archive-finalize-task --project . --task "completed task" --summary task_summary.md --docs-impact updated --memory-impact handoff-created --decision "Decision: ..." --gate "Gate: ..." --risk "Risk: ..." --next "Next step: ..." --snapshot --snapshot-mode auto
```

- `install-project --apply` is the one-command local installer. It uses the current directory as the project root, not the Git root; creates/updates `project.md` and `project.ithz`; adopts a workflow profile; and, if the current directory is inside Git, installs the ITHZ-aware Git diff/merge driver scoped to that directory. It does not run `git add`, `git commit` or `git push`.
- `--agent-intake auto` is the default first-install intake policy. It first builds a bounded deterministic repo dossier with project scale, directory summary, ranked candidate files and short redacted excerpts. Codex CLI then runs in read-only mode when available and is prompted to select important files/sections from that dossier. It stores only sanitized project summary/workflow/decision/gate/risk facts, candidate files, next steps and evidence gaps. It skips automatic host-model intake when an existing `project.ithz` is reused.
- `agent-intake-project` can be run explicitly later. `--mode codex-cli` requires Codex CLI; `--mode deterministic-only` records deterministic fallback facts; `--mode off` disables intake.
- Existing `.gitignore` files are preserved and only supplemented with missing local ITHZ/host artifacts. The installer does not overwrite project ignore rules.
- Existing `.gitattributes` files are preserved and only supplemented with `*.ithz merge=ithz diff=ithz binary` when Git driver installation is enabled.
- Temporary installer scratch is written under `.ithz-install/tmp/` and cleaned after success. Persistent host installer files are kept only with `install-project --apply --keep-install-artifacts` or the explicit `write-host-installers` command.
- `uninstall-project` is dry-run by default. Use `uninstall-project --apply` to remove `project.ithz`, `project.md`, `.ithz-install`, the ITHZ `.gitattributes` line, the ITHZ `.gitignore` block, local Git driver config and project-local MCP host configs that contain ITHZ markers, such as `.mcp.json`, `.antigravity/mcp.json`, `.cursor/mcp.json` and `.claude/mcp.json`. Add `--keep-project-md` to preserve the bootstrap file, or `--keep-host-configs` to preserve host config files.
- Native archive initialization defaults to `--index-mode compact-v2`. Use `--index-mode full` only for diagnostic comparison with the older full line index.
- Source file snapshots are off by default. Use `init-native-archive-memory --include-source-snapshot` only for diagnostics; normal `project.ithz` stores memory/index layers, not a backup copy of the codebase.
- `archive-ingest-project-memory` mines durable workflow/decision/gate/risk facts from user-provided docs into `project.ithz`.
- `archive-finalize-task` writes the end-of-task checkpoint into `project.ithz`, refreshes derived indexes and can create a snapshot. With `--snapshot-mode auto`, large archives defer snapshot creation while the checkpoint still succeeds. MCP write tools additionally support `async_mode=auto|sync|async`; in `auto`, large memory zones can queue finalization in a local background worker so the host receives a fast standard MCP response.
- `archive-adopt-project-workflow` creates or validates `project.md`, creates `project.ithz` if needed, mines existing Markdown docs and an onboarding prompt into a named workflow profile. With `--import-agent-history`, it appends project-scoped historical prompt summaries to the same archive and records author/time provenance.
- `workflow-ingest-prompt` updates one workflow profile from a prompt without overwriting another person's profile.
- `workflow-profile-status` lists workflow profiles stored in `project.ithz`.
- `workflow-context-pack` builds a context pack scoped to a workflow profile.
- `agent-history-discover` scans local agent-history roots in dry-run mode and reports project-matched prompt/response candidates. Use `--author` to make the audit identity explicit; otherwise Git config or OS user is used.
- `archive-import-agent-history` writes project-matched historical prompt/response summaries into `project.ithz` only when `--apply` is present. Existing Git-provided archives are appended, not replaced. Same-author duplicates are ignored; the same prompt from another author is kept as a separate audit record.
- Secret-like source files are skipped and secret-like payloads are redacted or blocked.
- Raw prompt/response capture remains explicit; default summary mode stores summaries and hashes.

Project ledger commands:

```powershell
python -m ithz_mcp ithz-add-claim --project <project> --claim-id claim_special_ithkor --text "Special ITHKOR has scoped finite/QPU diagnostic support." --scope finite/qpu --supporting-gate D20
python -m ithz_mcp ithz-block-claim --project <project> --claim-id blocked_gravity_claim --text "ITHKOR proves gravity" --reason "No physical D claim is authorized." --blocking-gate D20
python -m ithz_mcp ithz-can-i-claim --project <project> --claim "ITHKOR proves gravity?"
python -m ithz_mcp ithz-add-reviewer-note --project <project> --target D20 --text "First verify summary_found and status_matches_expected."
python -m ithz_mcp ithz-create-replication-pack-record --project <project> --pack-id D20 --witnesses 15 --positive 12 --negative-stop 3 --public-safe
python -m ithz_mcp ithz-get-project-ledger-summary --project <project>
```

- Project ledger records are stored inside `project.ithz` as first-class projections under `claims/`, `replication/`, `review/`, `ledger/` and `indexes/claim_index.json`.
- `ithz-can-i-claim` is conservative: a claim is allowed only when the ledger contains scoped support; matching blocked claims win.
- Ledger write MCP tools are exposed only in explicit write-enabled mode.

`archive-memory-status` also reports native runtime selection. By default the resolver uses `--native-exe` when provided, then `ITHZ_NATIVE_EXE`, then an AVX2/scalar auto-selection. AVX2 is selected only when runtime CPU detection reports AVX2 support; otherwise the scalar binary is used when present.

ITHZ-aware Git diff/merge driver commands:

```powershell
python -m ithz_mcp git-diff-ithz --archive project.ithz
python -m ithz_mcp git-merge-ithz --base base.ithz --ours ours.ithz --theirs theirs.ithz --out merged.ithz
python -m ithz_mcp install-git-drivers --repo .
python -m ithz_mcp git-driver-status --repo .
```

- `git-diff-ithz` prints a stable text summary for Git textconv diff.
- `git-merge-ithz` validates base/ours/theirs, unions independent append-only memory events, skips private/local-only prompt memory, blocks secret-like payloads, rebuilds derived indexes and writes a merge report.
- `install-git-drivers` writes `.gitattributes` and local Git config for `*.ithz merge=ithz diff=ithz binary`.
- These commands do not run `git commit`, `git push`, `git reset` or `git checkout`.

Real MCP compatibility commands:

```powershell
python -m ithz_mcp mcp-server --project <project> --mode read-only --protocol mcp
python -m ithz_mcp mcp-server --project <project> --mode write-enabled --protocol mcp --storage-profile native-archive
python -m ithz_mcp mcp-config-template --project <project> --client codex --storage-profile native-archive --out codex_mcp_config.json
python -m ithz_mcp mcp-config-template --project <project> --client codex --storage-profile native-archive --mode write-enabled --out codex_mcp_write_config.json
python -m ithz_mcp mcp-config-template --project <project> --client claude-code --out claude_mcp_config.json
python -m ithz_mcp mcp-config-template --project <project> --client antigravity --out antigravity_mcp_config.json
```

Generated configs include `agent_policy.memory_first=true` and `agent_policy.bootstrap_file=project.md`: compatible hosts should read `project.md`, then call ITHZ-MCP status/context-pack tools before broad codebase reads. Hard enforcement requires host-side staged tool permissions.

Write tools are available only in an explicit `write-enabled` MCP profile. The read-only profile does not expose `ithz_archive_auto_checkpoint`, `ithz_archive_finalize_task`, `ithz_archive_ingest_project_memory`, `ithz_archive_append_event`, `ithz_archive_record_prompt_response`, durable instruction write tools or project-ledger write tools such as `ithz_add_claim`, `ithz_block_claim`, `ithz_add_reviewer_note` and `ithz_create_replication_pack_record`.

The preferred write-enabled MCP tool for normal completed tasks is `ithz_archive_auto_checkpoint`. It is intended to be called by compatible hosts automatically at the end of the task before the final answer, but the write itself is still a visible MCP call and goes through the native `project.ithz` archive path. Large archives may return `queued=true`; the returned job log records whether the background native write completed.

macOS package commands:

```sh
chmod +x ithz_mcp_server.sh smoke_test.sh mcp_client_smoke.sh host_installers_macos/*.sh
./smoke_test.sh
host_installers_macos/install_codex_mcp.sh --project /path/to/project --apply
host_installers_macos/install_claude_code_mcp.sh --project /path/to/project --apply

Ubuntu package commands:

```sh
tar -xzf ithz-mcp-ubuntu.tar.gz
cd ithz-mcp-ubuntu
./install.sh
ithz-mcp version
./smoke_test_ubuntu.sh
```

Optional native archive fallback on Ubuntu:

```sh
sudo apt install build-essential cmake
./install_linux_native.sh
ithz-native-resolve
ithz-verify archive.ithz
ithz-list archive.ithz
ithz-extract-here archive.ithz
ithz-open-temp archive.ithz
```

`ithz-open-temp` opens an extraction-backed temporary folder. It is not a Linux Drive/FUSE provider.

The dedicated packaging gate is:

```sh
python -m ithz_mcp run-mcp28-ubuntu-package
```
```

The macOS MCP server path uses Python stdio. Use `--storage-profile native-archive` only when a compatible macOS `ithz-native` binary is available; otherwise keep the default legacy profile.

If the user gives a lasting workflow rule, project decision, validation gate or must-not-break rule during a task, write-enabled hosts should call one of:

- `ithz_record_workflow_rule`
- `ithz_record_project_decision`
- `ithz_record_gate_rule`
- `ithz_record_risk_rule`
- `ithz_ingest_user_instruction`

