CLI facet

Table of Contents

CLI entity commands live in ores.cli and follow a three-layer structure: an entity enum value, an options struct per operation, and an <entity>_parser class that owns command registration and dispatch. Phase 1 delivers list + export; Phase 2 delivers add + delete; Phase 3 adds recipe docs. Return to Knowledge.

Codegen gap

⚠ No codegen profile exists for this layer. Before creating CLI commands for any new entity:

  1. Create mustache templates in projects/ores.codegen/library/templates/.
  2. Add the new facet's node to the ores.cli physical-space graph (compass add facet) with its Archetypes table.
  3. Validate against an existing entity (e.g. currency).
  4. Only then use codegen to generate the layer.

Until the profile exists, see the recipes for the manual path — but treat this as a workaround, not the target state.

Registration steps

Every new entity requires four registration points:

  1. Add to the entity enum in include/ores.cli/config/entity.hpp.
  2. Create add_{entity}_options.hpp in include/ores.cli/config/ for the add command parameters (if applicable).
  3. Create <entity>_parser.hpp / <entity>_parser.cpp in include/ores.cli/parsers/ / src/parsers/.
  4. Register the parser in src/parsers/main_parser.cpp.

Options struct layout

Each operation that takes parameters gets its own options struct in include/ores.cli/config/. Required fields are plain members; optional fields use std::optional. Every struct includes a modified_by field. Option names use hyphens on the command line (--iso-code) but snake_case in the struct (iso_code).

Parser class layout

Each entity parser lives in include/ores.cli/parsers/{entity}_parser.hpp and src/parsers/{entity}_parser.cpp. It exposes register_commands(options_description&) and execute(const variables_map&), with one private method per operation (list, export, add, delete).

Operation shapes

Operation CLI subcommand Input Output
List =list –format {json\ table}= pagination params stdout
Export export --output <file> optional key filter file
Import import --input <file> file path persisted records
Add add --<field> <value> … options struct confirmation
Delete delete --<key> <value> key value confirmation

File locations

File Path
Entity enum include/ores.cli/config/entity.hpp
Add options include/ores.cli/config/add_{entity}_options.hpp
Parser header include/ores.cli/parsers/{entity}_parser.hpp
Parser impl src/parsers/{entity}_parser.cpp
Main parser src/parsers/main_parser.cpp (registration)

See also

Emacs 29.3 (Org mode 9.6.15)