Module commands 

Subcommand implementations. Each run takes the invocation Ctx plus its parsed arguments.

Modules

agent_rules

opys agent-rules — generate a rules-based editor’s always-on instruction file from the single canonical rule (templates::AGENT_RULE). No per-editor copies are kept in the repo; this writes the right file in the right place, adding any host-specific frontmatter.

block

opys block / opys unblock — record a directional blocker relationship between two documents of any type, through the corpus store.

cleanup

opys cleanup — strip struck-through (closed) references from every document. After this the closed documents have no remaining record except git history.

close

opys close — finish a document of a type that has a terminal status, deleting its file and striking every reference to it into a tombstone.

config

opys config … — project-config commands.

import

opys import — bulk-create documents of one type from a JSONL file in a single pass.

init

list

opys list — slice the inventory with one SQL SELECT over the corpus store: a JOIN per --tag/--field filter (AND semantics), column predicates for --type/--status, DISTINCT against multi-row matches, ordered by load (path) order.

new

query

opys query — run SQL over the live corpus store.

renumber

opys renumber — reassign IDs to documents that conflict with the base branch (same numeric part, different full IDs), keeping the IDs that already existed at the git merge-base and renumbering the ones that were added on a feature branch.

retire

opys retire — delete a document and reserve its id forever (ledger).

set_status

opys set-status — a guarded status transition through the corpus store.

show

opys show — print a document’s file verbatim (contractually the on-disk bytes, not the canonical reconstruction). The path is resolved through the corpus store; --refs appends code mentions of the id per [file_refs].

stats

opys stats — render the project’s configured [[stats]] sections. Each stat is a single SQL query (sql) run against an in-memory, throwaway relational view of the corpus (tables docs, tags, sections, fields); its result set is rendered as a markdown table. Pure read; no feature/type special-casing. The SQL engine is GlueSQL (pure Rust, in-memory).

sync

The full auto-sync pass: reconcile cross-references, linkify body prose, and relocate documents to their canonical layout path. Invoked by maybe_sync after every mutating command and by the opys sync command.

tag

opys tag — add/remove tags on documents through the corpus store.

tags

opys tags — enumerate the distinct tags across the inventory (or just their keys with --keys). Plain, sorted, one per line — easy to scan or pipe into opys list --tag.

verify

Functions

expand_ids

Parse the id argument of a bulk command into a deduplicated, order-preserving list. Bulk is opt-in via an explicit comma-separated list (FEAT-1,FEAT-2): a single id is just a one-element list. Space-separated ids are not accepted as positionals — clap rejects the extra positional, so shell word-splitting (e.g. an unintended $(opys list --format ids) expansion) fails loudly instead of silently widening a destructive batch. The literal - instead reads the list from stdin, where comma, space, and newline separation are all accepted (so opys list --format ids | opys close - works directly). Errors if no ids remain after trimming.

field_matches

Whether frontmatter fm satisfies every (key, value) filter (AND). A filter matches when the field is a scalar equal to the value, or a sequence containing an element equal to it; a missing or composite field never matches.

for_each_id

Run f against each id of a bulk command. A single id behaves exactly like the original one-shot command (its error propagates verbatim). With several ids it is best-effort: every id is attempted, each failure is reported, and an aggregate error is returned if any failed (so the exit code is nonzero) while the successful writes stand.

maybe_sync

Reconcile references, linkify bodies, and relocate docs to their canonical layout paths after a mutating command, unless --no-sync. Best-effort: a parse error elsewhere is reported but does not fail the mutation that already succeeded.

now_rfc3339

The current instant as an RFC3339 datetime, second precision (local time, falling back to UTC). Honors the OPYS_NOW environment override so tests can pin a deterministic timestamp; the override is returned verbatim.

parse_field_filters

Parse repeatable --field key=value list filters into (key, value) pairs.

split_csv

Split a comma-separated argument, trimming and dropping empties.

sync_quiet

Like maybe_sync but returns the result instead of printing — for callers (e.g. the TUI) that must not write to stdout/stderr and want to surface a sync failure themselves. Returns the number of documents synced (0 when --no-sync).

tag_key

The key portion of a tag, for filtering by key: the text before the first : or =. A bare tag is its own key (osc → osc), a namespaced or keyed tag exposes its head (area:parsing / priority=high → area / priority).

today

Today’s date as YYYY-MM-DD (local time, falling back to UTC).

touch

Stamp the auto-maintained timestamp fields on a user-initiated write: always refresh updated, and set created once (only if absent). Reconcile/linkify housekeeping must NOT call this — only meaningful user edits bump updated.