epoch_forge/docs/commands.md

59 lines
2.6 KiB
Markdown

# 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 `chr`, `town`, `event`, `calamity`, and `blocker`:
```text
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.