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 a cli profile entry to facet_catalogue.org.
  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.1 (Org mode 9.6.6)