Skip to content

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