epoch_forge/docs/commands.md

2.7 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 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. Its currently accepted --force flag has no effect.
  • 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.

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.