# Command reference Epoch Forge operates on the current working directory; it does not yet search parent directories. `efo --help` is the authoritative syntax. ## Repository and timeline - `efo init [--force]` creates the format-1.0 manifest, HEAD, index, worktree, 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 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 prune-future` previews later history; `--yes` moves it to a restorable backup. - `efo reset --hard ID_OR_TAG` previews a destructive rewind. Add `--yes` to align HEAD, index, and worktree to the target and permanently delete every newer epoch. This has no built-in undo; prefer `switch` plus `prune-future` when 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`: ```text efo add [NAME | --rng-name] [OPTIONS] efo edit [OPTIONS] efo show [NAME|@UUID] efo diff [--epoch-id ID_OR_TAG] efo del ``` 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 ` 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.