CLI design
authors: @toumorokoshi, @zph
This proposal outlines the design decisions and considerations for the Tome CLI.
Terminology
For the following discussion, {instance}
is defined as the instantiated tome (autogenerated shell function wrapping tome) or sub command.
Design Goals
tome instances should be compatible with sub instances
Unless there is a good argument otherwise, instances of tome should match behavior with instances of sub. This includes, but is not limited to:
- how tome executes scripts.
- how tome reads script metadata.
- the commands that are available as part of a tome instance.
The goal is to minimize effort to migrate from sub to tome, as long as it will not significantly hamper the ability for tome to be enhanced, or lead to a poor design decision (e.g. error-prone behavior).
Design Decisions
reserved commands for tome to add to instanced CLIs
Since a user can name their commands after any valid filename, it is possible for any command that is built into the tome-based CLIs to clobber a possible command the user would like to create.
As such, we are choosing to reserve the following subcommands on the {instance}
:
{instance} help
for help information about user script (ie:{instance} help my-script
){instance} commands
to list all available user scripts{instance} exec
for executing user scripts with conflicting names as instance subcommands{instance} tome
as a future cli namespace
More information about specific commands and their purpose are outlined below.
exec
The {instance} exec
subcommand allows for users to execute their user scripts that
have conflicting or shadowing names with {instance}
subcommands, ie help, commands, and exec.
For example if a user has a user script called help
they could execute it with
{instance} exec help
.
tome
It is valuable for tome to add new commands in the CLI themselves, as tome gains more functionality. So we should provide a pattern for how new commands are introduced. To preserve consistency and compatibility for users, we will attempt to limit instance subcommands to the ones declared in this design document.
We're choosing to pre-allocate the {instance} tome ...
namespace for future cli expansion.
sub-commands on tome itself
The tome CLI is only restricted by backwards compatibility with regards to the design of the CLI. As such, we can liberally add commands to the tome CLI.
Note: these are not to be confused with the {instance}
subcommands.
Currently the proposal for new commands is to include:
- init
- help
- exec
- complete
- commands