epoch_forge/docs/commands.md

4.5 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 .epoch 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 migrate --to 2 validates and previews migration without writing. Add --yes to create a byte-for-byte manifest backup and initialise the version-2 index/worktree. Migration is explicit and format-1 repositories remain supported.
  • 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 epoch reset permanently deletes every epoch after the current one.

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. Mutations write the current epoch immediately; staging does not exist in format 1. After format-2 migration, 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 and commits it; 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. Legacy efo epoch reset is deprecated and remains only for format-1 compatibility.

efo epoch summary and efo epoch tag edit format-2 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 format-2 layers and every immutable epoch.

efo show all lists every collection in the current epoch. show character, show town, show event, show calamity, and show blocker select one collection. Use <noun> show IDENTIFIER for full details of one entity.

Generation and output

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

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.