In Immersive, a command is a file which export 3 properties:

• command: the CLI command e.g config set <key> <value>
• description: a quick description of this command
• action: the function which will be executed whenever this command is called

Let's say we want to create a command to query a user in our database:

export const command = 'get <id>';
export const description = 'Get a user by id';

export const action = async ({ args, db, logger }) => {
  // Positional arguments (e.g id) can be accessed thanks to the `args` object
  const [id] = args._
  // Query the database
  const user = await db.get(id);
  if (!user) {
    logger.warn(`No user found with id ${id}`);
    return;
  }
  // Display the result inside a table
  logger.table({ name: 'Users', rows: [user] });
}

Immersive supports ES6 import/export inside commands thanks to esm. But you can use module.exports instead if you prefer.

Immersive supports async commands out of the box & will wait for your command to end before prompting for another

Immersive auto loads recursively your commands thanks to the commandsDirectory option.

import immersive from 'immersive';

const config = {
  // Path to the directory where commands are defined (required)
  commandsDirectory: path.join(__dirname, 'commands'),
};

immersive(config);

You just have to put all your commands inside this directory. Easy ! 😃

Commands are called with the following arguments:

• args: contains the result of the command parsing done by yargs-parser
• commands: the list of all available commands
• logger: a convenient logger (logger.error, logger.warn, logger.info, logger.debug, logger.log and logger.table
• command: the current command
• history: the command history object
• runCommand: a function which can be used to call a command inside another one 🤯
• immersiveConfig: the config object passed to immersive
• config: the user configuration
• env: the current event name
• and all your helpers

Immersive accepts a map of helpers that will be passed as arguments to the commands' action handler.

import immersive from 'immersive';

const config = {
  // Path to the directory where commands are defined (required)
  commandsDirectory: path.join(__dirname, 'commands'),
  // Will be accessible from commands as argument (optional)
  helpers: {
    db,
  },
};

immersive(config);

// Helpers are functions which are called during Immersive's setup
// and return an object/function that will be available in commands
function db() {
  return {
    get: id => database.users.get(id)
  };
}

Those helpers are convenient because you don't have to import them in every command and also for another feature: environments ➡️.

You can use the tab key to autocomplete your command. ⚡️

A history of the last commands is persisted automatically and can be accessed using the arrow keys (up and down) as in a normal shell.

To purge this history:

history clear

• repl: See REPL
• config list: Display configuration
• config set <key> <value>: Update configuration
• config get <key>: Get configuration value
• history clear: Clear history
• exit: Exit CLI
• help: Display help with the list of commands