CLI Reference

ghyll

ghyll run [dir] [--model <model>] [--resume]

Start an interactive coding session.

• dir — working directory (default: .)
• --model — lock to a specific model for the session (disables auto-routing and tier fallback)
• --resume — load the previous session’s final checkpoint summary as context. Restores plan mode state and links the new session to its predecessor.

ghyll run .                    # auto-detect model
ghyll run . --model glm5       # force GLM-5
ghyll run . --resume           # continue from last session
ghyll run ~/repos/myproject    # specify directory

ghyll init --op-id <id> [project-dir]

Bootstrap the project: discover contexts + roles, assemble the grid, persist .ghyll/grid.v1.yaml. Refuses to overwrite an existing grid. See Operator Guide — ghyll init for the full pipeline detail.

ghyll init --op-id alice@example.com .

ghyll init attest --op-id <id> [--dir <path>]

Tier 3 / gate-2 producer for init attestations: emits one on-the-spot record per arrow in the grid (AttestedByRole=init), persisted through the standard Record path. Idempotent on re-run. See Operator Guide — ghyll init attest.

ghyll init attest --op-id alice@example.com --dir .

ghyll config show

Display the loaded configuration.

ghyll memory log

Show the local checkpoint chain (hash, parent, turn, summary).

a1b2c3d4e5f6  2026-04-12 10:30  [m25] @alice  turn 5  fixed auth race condition
d4e5f6a1b2c3  2026-04-12 10:45  [glm5] @alice  turn 10  compaction summary

ghyll memory search <query>

Vector-search past checkpoints by semantic similarity.

ghyll memory search "auth race condition"

ghyll memory sync

Manually sync the checkpoint chain to/from the vault (push local checkpoints to the orphan branch, fetch remote ones). See Operator Guide — ghyll memory.

ghyll memory sync

ghyll memory fetch-embedder [--force] [--help]

Download the ONNX embedding model used by drift detection to [memory.embedder].model_path (default ~/.ghyll/models/gte-small.onnx). Reads [memory.embedder].model_url from ~/.ghyll/config.toml; falls back to the published GTE-micro URL when the config is absent.

Security and correctness contracts:

• Idempotent by default: existing files are kept. Use --force to re-download.
• HTTPS-only. http:// URLs are rejected unless the host is loopback (127.0.0.1, localhost, ::1) — supply-chain guard against a plaintext download of executable model weights. Redirect hops are re-validated: an https://-to-http:// 302 is refused.
• SHA-256 pin on the default URL — a CDN compromise or HF account takeover that doesn’t reproduce the exact bytes is rejected. When you override model_url, set [memory.embedder].model_sha256 alongside it to opt into the same verification; leaving it empty skips the check.
• Rejects 0-byte responses and Content-Type: text/html (the latter catches gated-repo login walls).
• Atomic write: streams to <base>.<rand>.tmp then renames on success. A partial download (network drop, server error, size-cap hit) leaves any existing file untouched.
• Size cap: 1 GiB. Misconfigured model_url pointing at a giant blob fails loud instead of filling the disk.
• Timeout: 15 minutes (covers the ~30-60 MB default on a constrained HPC uplink).
• HOME must be set (refuses to derive .ghyll/ paths from CWD).
• model_path accepts a leading ~/ (expanded to $HOME). Shell variables ($HOME/...) and other-user homes (~alice/...) are rejected with a directed error rather than silently treated as literal directory names.

ghyll memory fetch-embedder           # download if missing
ghyll memory fetch-embedder --force   # re-download
ghyll memory fetch-embedder --help    # show full usage

Custom backend example (set both URL and pin):

[memory.embedder]
model_url    = "https://internal.cdn/models/gte-small.onnx"
model_sha256 = "45b71fe98efe5f530b825dce6f5049d738e9c16869f10be4370ab81a9912d4a6"
model_path   = "~/.ghyll/models/gte-small.onnx"

The ONNX Runtime shared library is also required; the command prints a hint at the end with install pointers (macOS: brew install onnxruntime; Linux: github.com/microsoft/onnxruntime/releases). The hint also prints on the skip-when-exists path so an operator hitting “embedder unavailable” at session start after a successful download still sees the runtime install reminder.

ghyll engine status [--dir <path>]

Render a project-level summary of engine state: arrow / finding / requirement / amendment / evaluation-run / attestation counts. Reports ghyll-engine-status: missing when v2 was never initialized. See Operator Guide — ghyll engine status.

ghyll engine status --dir .

ghyll engine replay [--dir <path>]

Re-fan-out every persisted entity through the Journal observers, useful to rebuild derived state after a code change to a fan-out consumer. See Operator Guide — offline CLI commands for the full engine subcommand set.

ghyll engine replay --dir .

ghyll engine recover [--dry-run] [--dir <path>]

Preview crash recovery: open passes whose runner is gone, attestation-pending passes preserved across restart, evaluation runs reconciled from the JSONL audit log. --commit is refused; apply recovery by starting a session via ghyll run. See Operator Guide — ghyll engine recover.

ghyll engine recover --dry-run --dir .

ghyll engine verify-attestations [--dir <path>]

Walk .ghyll/attestations.jsonl and report records that violate the schema (missing fields, wrong kind/clause_id pairing, unknown verdict, §12.2 self-cert violation). Non-zero exit on failure. See Operator Guide — ghyll engine verify-attestations.

ghyll engine verify-attestations --dir .

ghyll arrow show <arrow-id> [--dir <path>]

Render one arrow’s live state: definition (source/target role, clauses, requirements), open findings, and all recorded attestations. See Operator Guide — ghyll arrow show.

ghyll arrow show A-checkout --dir .

ghyll version

Print the version string.

In-Session Commands

See Operator Guide — Slash commands for worked examples (op-id, attest, run-arrow, verdict modal).

Slash Commands

User-defined commands are loaded from .ghyll/commands/ in your repository (or ~/.ghyll/commands/ globally). Each .md file becomes a command. When typed, the file content is injected as a user message.

.ghyll/
  commands/
    review.md      # /review --- inject review prompt
    verify.md      # /verify --- inject verification checklist

Built-in commands (table above) take precedence over user-defined commands with the same name.

ghyll-vault

Running

ghyll-vault

Starts the team memory search server on :9090. Requires [vault] section in config.

ghyll-vault version

Print the version string.

Environment

ghyll reads configuration from ~/.ghyll/config.toml. The following paths are used:

The memory-sync git worktree is NOT in the project tree — it is created in a system temp dir via os.MkdirTemp (memory/sync.go:67) so the working copy stays clean.