epoch_forge/docs/commands.md

5.8 KiB

Command reference

Epoch Forge operates on the current working directory; it does not yet search parent directories. efo <command> --help is the authoritative syntax.

Repository and timeline

  • efo init [--force] creates the format-1.0 manifest, HEAD, index, worktree, and epoch/0/epochinfo.json. The normal form requires an empty directory; --force permits unrelated existing files but never overwrites .epoch or epoch 0.
  • efo recover deterministically rolls back a prepared replacement or verifies a committed one. It is safe to repeat.
  • efo lock inspect reports writer ownership. efo lock break --yes removes an abandoned lock only after explicit confirmation; run efo recover next.
  • efo status [EPOCH_ID] shows an epoch summary, tags, and entity counts.
  • efo epoch log [-c N] shows epochs around the current epoch.
  • efo epoch next creates and checks out the next snapshot. It refuses while later snapshots exist.
  • efo epoch switch ID_OR_TAG checks out an existing snapshot without deleting later ones.
  • efo epoch summary TEXT and efo epoch tag TAG annotate the current epoch.
  • efo epoch diff START [END] reports added, removed, and modified entities. END defaults to the current epoch.
  • efo epoch fsck performs a read-only consistency check of epoch IDs, tags, and entity UUIDs. It does not repair damage.
  • efo prune-future previews later history; --yes moves it to a restorable backup, removes tags into that future, and makes the next commit use the ID immediately after HEAD. Restoring the backup restores its allocator and tags.
  • efo reset --hard ID_OR_TAG previews a destructive rewind. Add --yes to align HEAD, index, and worktree to the target and permanently delete every newer epoch. This has no built-in undo; prefer switch plus prune-future when recovery may be needed.

Entities

The built-in nouns are org, chr, town, event, calamity, and blocker. character aliases chr; organization and organisation alias org:

efo <noun> add [NAME | --rng-name] [OPTIONS]
efo <noun> edit <NAME|@UUID> [OPTIONS]
efo <noun> show [NAME|@UUID]
efo <noun> diff <NAME|@UUID> [--epoch-id ID_OR_TAG]
efo <noun> del <NAME|@UUID>

Names match by prefix. @UUID is the stable form printed in detailed output; short UUID prefixes are accepted. Avoid ambiguous prefixes.

Common add/edit options include --stats key:value ..., --position x,y, --duration, --bounds, --effect, faction/reach/description/relationship options, and prestige controls. edit --delta adds supplied stats rather than replacing them. See nested help (for example efo chr add --help) for exact syntax and values. Persistent normalized stats are clamped to 0..=120; growth and event/blocker modifiers use -120..=120; population remains an unbounded non-negative count for persistent entities. Entity mutations edit only the worktree. Use efo diff, efo stage --all, efo stage --world, or efo stage --kind KIND ID..., and efo diff --staged to prepare history. efo restore --staged ... copies HEAD into the index; efo restore --worktree ... copies the index into the worktree. Both restore modes require either --all or an entity kind and IDs. efo commit -m MESSAGE refuses unstaged or empty commits, creates an immutable epoch using a manifest-last transaction, and realigns all three layers. efo log shows the resulting parent-linked history newest first. efo switch ID requires clean state and changes all layers without reusing epoch IDs. efo revert ID applies that epoch's inverse to the worktree for review; it can be undone with restore --worktree --all. revert ID --commit prints a warning and immediately creates the inverse commit. Overlap with later changes aborts without mutation. efo prune-future previews future epochs, while --yes moves them into a backup. Restore using the exact command printed after pruning; this also restores the former next-epoch allocator and tags. After pruning, new linear history begins at HEAD + 1 rather than retaining a gap for the removed epochs. efo reset --hard ID --yes is the explicitly destructive alternative: it discards transient changes, removes newer epochs without a backup, removes tags that point to them, and restarts the epoch allocator after the retained target.

efo epoch summary and efo epoch tag edit worktree metadata; stage --world selects it. efo epoch next requires a clean worktree, includes already staged changes, advances entity time, and commits one new monotonic ID. efo epoch fsck validates all state layers and every immutable epoch.

efo show defaults to every collection. show character, show town, show event, show calamity, show organization, and show blocker select one. Filter with --name TEXT, --text TEXT, or --position X,Y; select a committed snapshot with --epoch ID_OR_TAG. --detail short|long|full controls output density. efo show epoch lists committed epoch summaries and accepts the same --epoch and detail options. Use <noun> show IDENTIFIER for the complete details of one entity by its name or stable ID.

Generation and output

efo gen character|town|event|exotic|calamity|blocker prints generated content without creating or changing repository files.

efo gen world --level event|settlement|region|world --seed N previews a deterministic generated world using embedded configuration. --config PATH selects an editable JSON override. --apply explicitly replaces only the worktree; undo it with efo restore --worktree --all, or stage and commit it through the ordinary workflow.

Output is human-readable Unicode, with Nerd Font icons enabled by default. A portable build replaces those icons with textual/standard-Unicode labels; use cargo install --path bin_efo --no-default-features. Stable JSON output is planned. A panic is always a bug.