Termost

A framework to build your next CLI application: Get the most of your termin...

HTTP client • Fetch • AJAX
adbayb/termosttermost

README

💻 Termost


Get the most of your terminal

✨ Features


Termost allows building command line tools in a minute thanks to its:

Fluent syntax to express your CLI configurations with instructions such as:
Subcommand support
Long and short option support
User input support
Task support

Shareable output between instructions
Auto-generated help and version metadata
TypeScript support to foster a type-safe API
Built-in helpers to make stdin/stdout management a breeze (including exec, and message helpers...)

🚀 Quickstart


Install the library:

  1. ``` shell
  2. # Npm
  3. npm install termost
  4. # Pnpm
  5. pnpm add termost
  6. # Yarn
  7. yarn add termost
  8. ```

Once you're done, you can play with the API:

  1. ``` ts
  2. #!/usr/bin/env node

  4. import { helpers, termost } from "termost";

  6. type ProgramContext = {
  7. globalFlag: string;
  8. };

  10. type DebugCommandContext = {
  11. localFlag: string;
  12. };

  14. const program = termost<ProgramContext>("CLI example", {
  15. onException(error) {
  16.   console.error(`Error logic ${error.message}`);
  17. },
  18. onShutdown() {
  19.   console.log("Clean-up logic");
  20. },
  21. });

  23. program.option({
  24. key: "globalFlag",
  25. name: { long: "global", short: "g" },
  26. description:
  27.   "A global flag/option example accessible by all commands (key is used to persist the value into the context object)",
  28. defaultValue:
  29.   "A default value can be set if no flag is provided by the user",
  30. });

  32. program
  33. .command({
  34.   name: "build",
  35.   description:
  36.    "A custom command example runnable via `bin-name build` (command help available via `bin-name build --help`)",
  37. })
  38. .task({
  39.   label: "A label can be displayed to follow the task progress",
  40.   async handler() {
  41.    await fakeBuild();
  42.   },
  43. });

  45. program
  46. .command<DebugCommandContext>({
  47.   name: "debug",
  48.   description: "A command to play with Termost capabilities",
  49. })
  50. .option({
  51.   key: "localFlag",
  52.   name: "local",
  53.   description: "A local flag accessible only by the `debug` command",
  54.   defaultValue: "local-value",
  55. })
  56. .task({
  57.   handler(context, argv) {
  58.    helpers.message(`Hello, I'm the ${argv.command} command`);
  59.    helpers.message(`Context value = ${JSON.stringify(context)}`);
  60.    helpers.message(`Argv value = ${JSON.stringify(argv)}`);
  61.   },
  62. });

  64. const fakeBuild = async () => {
  65. return new Promise((resolve) => {
  66.   setTimeout(resolve, 3000);
  67. });
  68. };
  69. ```

Depending on the command, the output will look like this (bin-nameis the program name automatically retrieved from the package.json>name):

✍️ Usage


Here's an API overview:

command({ name, description })

The API creates a new subcommand context.Please note that the root command context is shared across subcommands but subcommand's contexts are scoped and not accessible between each other.

  1. ``` ts

  3. ```

input({ key, label, type, skip, ...typeParameters })

The API creates an interactive prompt.It supports several types:

  1. ``` ts

  3. ```

option({ key, name, description, defaultValue, skip })

The API defines a contextual CLI option.The option value can be accessed through its property from the current context.

  1. ``` ts

  3. ```

task({ key, label, handler, skip })

The executes a handler (either a synchronous or an asynchronous one).The output can be either:

Displayed gradually if no is provided
Displayed until the promise is fulfilled if a property is specified (in the meantime, a spinner with the label is showcased)

  1. ``` ts

  3. ```

🤩 Built with Termost


Quickbundle The zero-configuration bundler powered by ESBuild

💙 Acknowledgements


This project is built upon solid open-source foundations. We'd like to thank:

enquirer for managing inputinternals
listr2 for managing taskinternals

📖 License


MIT