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.epochandepoch/0/epochinfo.json. The normal form requires an empty directory;--forcepermits unrelated existing files but never overwrites.epochor epoch 0.efo migrate --to 2validates and previews migration without writing. Add--yesto create a byte-for-byte manifest backup and initialise the version-2 index/worktree. Migration is explicit and format-1 repositories remain supported.efo recoverdeterministically rolls back a prepared replacement or verifies a committed one. It is safe to repeat.efo lock inspectreports writer ownership.efo lock break --yesremoves an abandoned lock only after explicit confirmation; runefo recovernext.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 nextcreates and checks out the next snapshot. It refuses while later snapshots exist.efo epoch switch ID_OR_TAGchecks out an existing snapshot without deleting later ones.efo epoch summary TEXTandefo epoch tag TAGannotate the current epoch.efo epoch diff START [END]reports added, removed, and modified entities.ENDdefaults to the current epoch.efo epoch fsckperforms a read-only consistency check of epoch IDs, tags, and entity UUIDs. It does not repair damage.efo epoch resetpermanently 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.