epoch_forge/docs/commands.md

2.9 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. This is an opt-in Phase 4 transition: ordinary commands deliberately refuse format 2 until the staging checkpoint lands.
  • 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 yet in format 1.

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.