5.0 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, andepoch/0/epochinfo.json. The normal form requires an empty directory;--forcepermits unrelated existing files but never overwrites.epochor epoch 0.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 prune-futurepreviews later history;--yesmoves it to a restorable backup.efo reset --hard ID_OR_TAGpreviews a destructive rewind. Add--yesto align HEAD, index, and worktree to the target and permanently delete every newer epoch. This has no built-in undo; preferswitchplusprune-futurewhen 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. 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. 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 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.
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.