\n\n# quire-cli\n\n[](https://discord.gg/6qsdhSPE)\n\n`quire-cli` is a static command-line wrapper around\n[`quire-rs`](https://github.com/agent-ix/quire-rs). It gives agents and\nhumans one fast binary for parsing, extracting, looking up, editing,\nvalidating, inspecting the input contract of Markdown artifacts, and exporting\nsource-grounded assurance facts.\nvalidating, inspecting Markdown contracts, and evaluating module-supplied\nclause sets.\n\nThe crate is intentionally a thin process boundary: Markdown parsing,\nextraction, and structural validation live in `quire-rs`.\n\n## Commands\n\n```bash\nquire assurance --scope --module --repository \\\n --revision --expect-module \\\n [--expect-schema ]...\nquire parse \nquire lookup (--heading [--level <1..6>] | --id | --block-id ) [--content]\nquire edit (--heading | --block-id ) --content [--out ]\nquire extract --module [--archetype ]\nquire validate ... [--scope ] [--module ] [--archetype ]\nquire validate --okf [--scope ] [--module ]\nquire schema --module \nquire clauses evaluate --module --authority --set --version [--context KEY=VALUE]...\nquire clauses diff --module --authority --set --before-version --after-version \n```\n\nGlobal flags:\n\n| Flag | Default | Purpose |\n|------|---------|---------|\n| `--diagnostics-format ` | `human` | stderr diagnostic encoding |\n| `--pretty` | off | indented JSON output for JSON-emitting commands, including `assurance` |\n\nExit codes:\n\n| Code | Meaning |\n|------|---------|\n| 0 | success |\n| 1 | user error: parse failure, schema violation, unknown archetype, I/O error, lookup miss |\n| 2 | argv error: missing required flag, unknown flag, invalid flag combination |\n| 134 | panic, never expected |\n\n## Install\n\n### npm (prebuilt binary — recommended)\n\nPublished on the public npm registry as [`@agent-ix/quire-cli`](https://www.npmjs.com/package/@agent-ix/quire-cli).\nA per-platform optional dependency carries the prebuilt binary, so no Rust\ntoolchain and no `quire-rs` checkout is needed — just install:\n\n```bash\nnpm install -g @agent-ix/quire-cli # or: npx @agent-ix/quire-cli --help\nquire --help\n```\n\nPrebuilt targets: linux-x64, linux-arm64 (musl/static), darwin-arm64, win32-x64.\nLinux x64 covers Intel and AMD; win32-x64 covers Intel and AMD Windows.\n\n### Prebuilt tarball\n\nEach [release](https://github.com/agent-ix/quire-cli/releases) attaches a\n`quire--.tar.gz` (`.zip` on Windows) plus `SHA256SUMS.txt`.\nDownload, verify, and drop `quire` on your `PATH`.\n\n### From source\n\n`quire-cli` builds on [`quire-rs`](https://github.com/agent-ix/quire-rs), fetched\nfrom GitHub at build time, so configure `cargo` with `net.git-fetch-with-cli = true`.\n\n```bash\ncargo install --git https://github.com/agent-ix/quire-cli\n# or, from a checkout:\ncargo build --release && target/release/quire --help\n```\n\nDuring development, `target/debug/quire` is fine for local testing.\n\n## Usage Instructions\n\n### Parse And Outline Markdown\n\nParse a document into a `QuireDocument` JSON envelope:\n\n```bash\nquire --pretty parse spec/functional/FR-001.md\n```\n\nPrint a compact outline:\n\n```bash\nquire parse spec/functional/FR-001.md \\\n | jq -r '.. | objects | select(has(\"heading\") and has(\"level\")) | \"\\(.level) \\(.heading) id=\\(.id) block_id=\\(.block_id // \"-\") lines=\\(.start_line)-\\(.end_line)\"'\n```\n\nInspect frontmatter:\n\n```bash\nquire parse spec/functional/FR-001.md | jq '.frontmatter'\n```\n\n### Lookup One Section\n\nFetch one parsed section as JSON:\n\n```bash\nquire lookup spec/functional/FR-001.md --heading Behavior\nquire lookup spec/functional/FR-001.md --heading \"Document Title\" --level 1\nquire lookup spec/functional/FR-001.md --id behavior-L14\nquire lookup spec/functional/FR-001.md --block-id blk-behavior\n```\n\nFetch only section body bytes:\n\n```bash\nquire lookup spec/functional/FR-001.md --heading Acceptance --content\nquire lookup spec/functional/FR-001.md --block-id blk-behavior --content\n```\n\n`--id` is generated as `-L` and can change when lines move.\nFor stable machine addressing, author headings with Pandoc block IDs:\n\n```markdown\n## Behavior {#blk-behavior}\n```\n\nThen use:\n\n```bash\nquire lookup doc.md --block-id blk-behavior\n```\n\n### Edit One Section\n\nReplace a single section's body (or a full block) without rewriting the rest of\nthe document — frontmatter and every untouched section stay byte-identical:\n\n```bash\n# Replace the Acceptance Criteria body in place (new content from stdin)\nquire lookup FR-001.md --heading \"Acceptance Criteria\" --content # read current\nquire edit FR-001.md --heading \"Acceptance Criteria\" --content new-ac.md --out FR-001.md\n\n# Replace a full stable block (heading line + body) from stdin\nquire edit FR-001.md --block-id blk-behavior --content - < new-block.md\n```\n\n`--heading` content is the section BODY (everything after the heading line);\n`--block-id` content is the FULL block (heading line, with its `{#blk-id}`\nattribute, plus the body). Omit `--out` to write the updated document to stdout.\n\n### Extract Records And Links\n\nRun an archetype's `body_extraction` DSL and collect edges:\n\n```bash\nquire extract spec/objects/EX-001.md --module ./extract-mod\n```\n\nOverride archetype inference when needed:\n\n```bash\nquire extract EX-001.md --module ./extract-mod --archetype ExtractSample\n```\n\nShow only harvested edges:\n\n```bash\nquire extract EX-001.md --module ./extract-mod | jq '.edges'\n```\n\n`extract` does not auto-validate. Run `validate` separately for context\nJSON schema checks.\n\n### Export Source-Grounded Assurance Facts\n\nEmit quire-rs's closed `quire-assurance` v1 envelope over a bounded repository:\n\n```bash\nquire assurance \\\n --scope . \\\n --module ./.ix/modules/spec-artifacts-process \\\n --repository agent-ix/example \\\n --revision 0123456789abcdef0123456789abcdef01234567 \\\n --expect-module spec-artifacts-process@0.1.0 \\\n --expect-schema spec-artifacts-process/FR@<64-lowercase-hex-digest>\n```\n\nDocuments come only from `/spec`; source symbols come from ``\nwith `spec/` and module-declared source exclusions omitted. The module path,\nrepository identity, full revision, module version, and complete active-schema\ndigest set are explicit. A missing, extra, or mismatched premise exits non-zero\nbefore stdout. A successful corpus may contain empty arrays; an unreadable\ndocument remains explicit as an `unknown` observation with a reason.\n\nThe command performs static parsing and extraction only. It invokes no Git,\ntest, proof, solver, package manager, consumer, or network operation, adds no\nverdict, and does not append the CLI's ordinary provenance object to the closed\nupstream payload. Compact JSON is deterministic; global `--pretty` re-indents\nthe already validated compact bytes and changes whitespace only. Diagnostics\nalways use stderr.\n\n### Validate A Markdown Document\n\nStructurally validate an authored document against its archetype. The archetype\nis resolved from the frontmatter `type` unless `--archetype` overrides\nit. Relative document globs are resolved under `--scope`; in scoped mode Quire\nloads modules from that scope, `--scope ./.ix/modules` style plugin roots, and\n`IX_SCHEMA_PATH`. quire-rs runs the archetype's `body_extraction` asserts (required-section\npresence, non-placeholder content, table columns/rows, list items, id patterns)\nplus frontmatter-schema and per-level heading uniqueness:\n\n```bash\nquire validate --scope . \"spec/**/*.md\"\nquire validate --scope . \"spec/functional/*.md\" \"spec/usecase/*.md\"\nquire validate ./spec/functional/FR-001.md --module ./iso\nquire validate ./FR-001.md --module ./iso --archetype FR\ncat FR-001.md | quire validate - --module ./iso --archetype FR\n```\n\nOn success `validate` exits 0 with no output. On failure it exits 1 and writes\nthe line-numbered quire-rs diagnostics (naming the archetype, section/assert, and\nreason: `missing`/`empty`/`placeholder`/`assert`/`frontmatter`/`duplicate-heading`)\nto stderr — verbatim, the CLI adds no validation logic of its own.\n\nEvery document also satisfies the base **concept** contract before its archetype\nruns: `type` is required and non-empty (the OKF discriminator), and the optional\nOKF fields `description` (string) and `tags` (string array) are type-checked when\npresent.\n\n### Validate An OKF Bundle (`--okf`)\n\n`--okf` reads a *foreign* OKF bundle directory under a permissive posture for\nportability. `type` is still required and non-empty, but unknown types, broken\n`ix://` links, and `index.md` completeness gaps (every sibling artifact must be\nlisted; the bundle-root `index.md` must carry `okf_version`) are reported as\n**warnings** (exit 0) rather than hard errors. An untyped document is still a\nhard error.\n\n```bash\nquire validate --okf path/to/bundle --module ./iso\nquire validate --okf --scope path/to/repo # bundle root is path/to/repo/spec\n```\n\nWith no positional bundle the root is **`/spec`**, not `--scope` itself\n(quire-rs CR-045 two roots): the corpus is walked from `spec/` while the\nmodule's path-bound declarations keep resolving against the scope. A `--scope`\nwith no `spec/` directory is an error, never a silent repository-wide crawl —\npass the bundle as the positional argument when it is self-contained.\n\nThe two forms resolve a module's path-bound declarations differently on\npurpose: `--scope` keeps them repository-relative, while a positional bundle\nis treated as self-contained and resolves them against itself. Use `--scope`\nwhen the module declares paths like `document: spec/tests.md`.\n\nWithout `--okf`, bundle directories validated via `--scope \"spec/**/*.md\"` keep\nthe strict per-file posture (archetype conformance, resolvable references,\ncomplete indexes are all hard requirements).\n\n### Inspect An Archetype's Input Contract\n\nEmit the archetype input contract — the frontmatter JSON Schema plus the\n`body_extraction` asserts (required headings, table columns, id-patterns) that\n`validate` enforces — as deterministic JSON. This is the same contract an\nauthoring agent fills; there is no template-variable list (templates were\nremoved):\n\n```bash\nquire schema FR --module ./iso\nquire --pretty schema FR --module ./iso\n```\n\nUnknown archetypes exit 1 with `UnknownArchetype` on stderr.\n\n## Agent Skills\n\nThis repository ships Codex-style agent skills under `skills/`. They are\nintended to be packaged with or installed from `quire-cli` so agents can use\nthe CLI consistently without relearning command patterns.\n\nAvailable skills:\n\n| Skill | Slash-style name | Purpose |\n|-------|------------------|---------|\n| `explore-markdown` | `/explore-markdown` | Outline Markdown and fetch targeted sections with `parse` and `lookup`. |\n| `write-markdown` | `/write-markdown` | Author Markdown artifacts against an archetype's input contract via `schema` + `validate`. |\n| `validate-markdown` | `/validate-markdown` | Check authored Markdown structure with `validate`, `parse`, and `lookup`. |\n| `link-markdown` | `/link-markdown` | Inspect relationships, `ix://` links, and blast radius with `extract`. |\n\nEach skill has:\n\n```text\nskills//SKILL.md\nskills//agents/openai.yaml\n```\n\nWhen adding a new shipped skill, keep it general, command-oriented, and\ndomain-neutral. Domain review guidance belongs in domain-specific skills,\nnot here.\n\nValidate skills with:\n\n```bash\npython3 path/to/quick_validate.py skills/explore-markdown\npython3 path/to/quick_validate.py skills/write-markdown\npython3 path/to/quick_validate.py skills/validate-markdown\npython3 path/to/quick_validate.py skills/link-markdown\n```\n\n## Safety\n\nPath safety is part of the CLI contract:\n\n- `--module`, `--out`, `--content`, and positional document paths reject `..`\n traversal where the command applies path safety.\n- Symlink escapes are rejected.\n- A positional `-` reads from stdin by design (path-safety-exempt).\n- The CLI makes no network calls in normal operation; tests audit this with\n `strace`.\n\n## Development\n\n```bash\nmake build # release build\nmake test # cargo test, including integration tests and audits\nmake lint # clippy -D warnings\nmake fmt-check # rustfmt --check\nmake deny # cargo deny check licenses\nmake deny-bans # cargo deny check bans\nmake audit-unsafe # every unsafe block carries a // SAFETY: comment\nmake audit-thin-boundary # src/ stays a thin wrapper over quire-rs\nmake refresh-fixtures # re-sync tests/fixtures/iso from ../quire-rs\nmake ci # local CI gauntlet\n```\n\nThe release binary is audited to link only baseline system libraries on\nLinux. See `tests/audit_ldd.rs`.\n\n## Spec And Plan\n\nRequirements live in `spec/`; the implementation plan and task index live in\n`plan/`. The traceability matrix in `spec/tests.md` maps acceptance criteria\nto integration tests, benchmarks, or static audits.\n\n## License\n\nAGPL-3.0-or-later\n",
"bytes": 13277,
"sha": "5e776a4e3c6c2b866505107e1fc0a05abc80d9f7212ff20ffc481397c8bc1efe",
"repo_slug": "agent-ix/quire-cli",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/okf_agent_ix_quire_cli_spec_index_md_33cbce97/readme"
}
![\"Quire\"](\"logo.png\")
\n