Writing commands

Every team, repo, and workspace has unique needs. oneRepo shines when it comes to doing what you need at the right time.

oneRepo commands are an extended version of the Yargs command module, written as ESM and TypeScript compatible modules. By default, command files can be placed in a commands/ folder at the repository root and within any workspace and they will automatically be registered. This directory can be changed by setting the commands.directory setting in the root configuration.

Commands are required to implement the following exports:

Export	Type	Description
name	string | Array<string>	The command’s name. If provided as an array, all values will be considered aliases for the same command. Any value can also be '$0', which is a special token that allows this command to be the default for the parent command.
description	string | false	A helpful description. If set to false, the command will be hidden from help output unless --show-advanced is included with --help. Note: unlike in Yargs, this export must be description and not describe.
builder	Builder<T>	A function that helps parse the command-line arguments
handler	Handler<T>	Asynchronous function that is invoked for the command

Tutorial

Section titled Tutorial

A basic command

Section titled A basic command

Let’s create a custom command for our team for creating new branches using a standard naming format. This will help make it quick and easy when working on many different things to organize and avoid conflicts with each other when pushing our branches for peer review.

1. Create a command

   ./commands/new-branch.ts

   import type { Builder, Handler } from 'onerepo';
   
   export const command = 'new-branch';
   
   export const description = 'Create a new branch using our team’s standard naming format.';
   
   export const builder: Builder = (yargs) => yargs.usage(`$0 ${command}`);
   
   export const handler: Handler = async (argv) => {
     // TODO
   };

2. Add arguments

   For our branch names, we want to follow the common structure: <username>/[issue-number]/<description>, where [issue-number] is optional. Let’s start by setting up the input options for the issue number and description.

   If you’re using TypeScript, be sure to add the type for the arguments that will be found by the builder and passed through to the handler. This can be done by defining each as Builder<Args> and Handler<Args>, respectively. By doing so, the builder will be checked via tsc to ensure that all options are accounted for correctly and the first argument passed to our handler function (argv) will include the appropriate shape.

   Note the difference between optional and required arguments: the required description argument includes an option demandOption set to true:

   ./commands/basic.ts

   import type { Builder, Handler } from 'onerepo';
   
   export const command = 'new-branch';
   
   export const description =
     'A basic command that shows the minimum requirements for writing commands with oneRepo';
   
   type Args = {
     issue?: number;
     description: string;
   };
   
   export const builder: Builder<Args> = (yargs) =>
     yargs
       .usage(`$0 ${command}`)
       .option('issue', {
         type: 'number',
         description: 'The GitHub issue number for this change.',
       })
       .option('description', {
         type: 'string',
         description: 'A short and concise description of the work.',
         demandOption: true,
       });
   
   export const handler: Handler<Args> = async (argv, { logger }) => {
     const { issue, description } = argv;
     logger.info(`TODO: create new branch for #${issue} with description "${description}"`);
   };

   $ one new-branch --issue 123 --description "my issue description"
    INFO TODO: create new branch for #123 with description "my issue description"
    ■ ✔ Completed 48ms

   More options

   For more in-depth documentation, refer to the Yargs .options() documentation.

3. Getting your username

   You may have noticed that we skipped the <username> in our input arguments for creating new branches. That’s because we should be able to get the username from the operating system and reduce the extra burden on developers needing to add that in for every branch.

   To get the username, we can use Node’s os.userInfo() command:

   ./commands/basic.ts

   import { userInfo } from 'node:os';
   
   import type { Builder, Handler } from 'onerepo';
   
   export const command = 'new-branch';
   
   export const description =
     'A basic command that shows the minimum requirements for writing commands with oneRepo';
   
   type Args = {
     issue?: number;
     description: string;
   };
   
   export const builder: Builder<Args> = (yargs) =>
     yargs
       .usage(`$0 ${command}`)
       .option('issue', {
         type: 'number',
         description: 'The GitHub issue number for this change.',
       })
       .option('description', {
         type: 'string',
         description: 'A short and concise description of the work.',
         demandOption: true,
       });
   
   export const handler: Handler<Args> = async (argv, { logger }) => {
     const { issue, description } = argv;
     const { username } = userInfo();
     logger.info(
       `TODO: create new branch for ${username} with issue #${issue} and description "${description}"`,
     );
   };

   Now, when running our command, we can see our username. For this example, we’ll use the creator of JavaScript, Brendan Eich’s username, brendaneich:

   $ one new-branch --issue 123 --description "my issue description"
    INFO TODO: create new branch for brendaneich with issue #123 and description "my issue description"
    ■ ✔ Completed 48ms

4. Logic & scripts

   Now that we have the basic plumbing and all of the input information we need, it’s time to actually make our command create new branches.

   ./commands/basic.ts

   import { userInfo } from 'node:os';
   
   import { run } from 'onerepo';
   
   import type { Builder, Handler } from 'onerepo';
   
   export const command = 'new-branch';
   
   export const description =
     'A basic command that shows the minimum requirements for writing commands with oneRepo';
   
   type Args = {
     issue?: number;
     description: string;
   };
   
   export const builder: Builder<Args> = (yargs) =>
     yargs
       .usage(`$0 ${command}`)
       .option('issue', {
         type: 'number',
         description: 'The GitHub issue number for this change.',
       })
       .option('description', {
         type: 'string',
         description: 'A short and concise description of the work.',
         demandOption: true,
       });
   
   export const handler: Handler<Args> = async (argv) => {
     const { issue, description } = argv;
     const { username } = userInfo();
   
     // Ensure the description is suitable for git branch names by removing non-word characters
     const sanitizedDescription = description.replace(/[\W]+/g, '-');
     // Construct the branch name replacing empty or no issue with 'no-issue'
     const branchName = `${username}/${issue || 'no-issue'}/${sanitizedDescription}`;
   
     // Use oneRepo's subprocessing, `run` to run commands:
     await run({
       name: 'Create branch',
       cmd: 'git',
       args: ['checkout', '-b', branchName, 'origin/main'],
     });
   };

   One last time, let’s run our command and create a new branch for adding the command:

   $ one new-branch --issue 123 --description "create new-branch command"
    ┌ Create branch
    └ ✔ 985ms
   ■ ✔ Completed 1028ms
   
   $ git rev-parse --abbrev-ref HEAD
   brendaneich/123/create-new-branch-command

Nesting commands

Section titled Nesting commands

Commands may be nested for organization purposes. Nesting can help create a logical hierarchy and flow for users when working with various aspects of your monorepo’s tooling. Using our previous example of new-branch it may make sense to create multiple commands for working with branches.

In this example, let’s make our new branch command accessible by running one branch new and set up the plumbing for more sub-commands of branch in the future.

1. Add a parent command

   To create a parent command that can have nested sub-commands, use the .commandDir() function in the builder to reference a relative path from the current file that holds the sub-commands. Let’s assume we want to create a suite of git branch management commands to make it easier for developers to use standard branch naming conventions and more:

   ./commands/branch.ts

   import type { Builder, Handler } from 'onerepo';
   
   export const command = 'branch';
   
   export const description = 'A suite of branch management commands';
   
   export const builder: Builder = (yargs) =>
     yargs.usage(`$0 ${command}`).commandDir('./branch').demandCommand(1);

   This function uses the same logic for finding commands as all other commands are found. You can configure various aspects of this logic using the RootConfig #commands setting.

   Notice that we also have not defined or exported a handler function, however, we have defined demandCommand(1). This signals to the CLI that when this command is run without a sub-command, that it should return the help documentation and exit immediately.

2. Move the sub-command

   Next ensure we have a sub-directory ./commands/branch, as previously used for the commandDir() argument in our builder. Then we can create our new command with the basic 4-export structure command, description, builder, and handler

   mkdir -p commands/branch
   git mv commands/new-branch.ts commands/branch/new.ts

   We should now have a file tree that looks like this:

   • Directorycommands/

     • Directorybranch/

       • new.ts
     • branch.ts

3. Update the command name

   Lastly, we need to remember to update the command’s name. We do this by changing the command export variable:

   ./commands/branch/new.ts

   import { userInfo } from 'node:os';
   import { run } from 'onerepo';
   import type { Builder, Handler } from 'onerepo';
   
   export const command = 'new-branch';
   export const command = 'new';
   
   export const description =
     'A basic command that shows the minimum requirements for writing commands with oneRepo';
   
   type Args = {
     issue?: number;
     description: string;
   };
   
   export const builder: Builder<Args> = (yargs) =>
     yargs
       .usage(`$0 ${command}`)
       .option('issue', {
         type: 'number',
         description: 'The GitHub issue number for this change.',
       })
       .option('description', {
         type: 'string',
         description: 'A short and concise description of the work.',
         demandOption: true,
       });
   
   export const handler: Handler<Args> = async (argv) => {
     const { issue, description } = argv;
     const { username } = userInfo();
   
     // Ensure the description is suitable for git branch names by removing non-word characters
     const sanitizedDescription = description.replace(/[\W]+/g, '-');
     // Construct the branch name replacing empty or no issue with 'no-issue'
     const branchName = `${username}/${issue || 'no-issue'}/${sanitizedDescription}`;
   
     // Use oneRepo's subprocessing, `run` to run commands:
     await run({
       name: 'Create branch',
       cmd: 'git',
       args: ['checkout', '-b', branchName, 'origin/main'],
     });
   };

   That’s it! We can now run our new branch command using the parent/sub-command pattern:

   $ one branch new --issue 123 --description "create new-branch command"
    ┌ Create branch
    └ ✔ 985ms
   ■ ✔ Completed 1028ms
   
   $ git rev-parse --abbrev-ref HEAD
   brendaneich/123/create-new-branch-command

4. Adding more commands

   Just like with the previous commands/branch/new.ts command file. We can continue adding commands to the commands/branch directory and they will automatically become sub-commands of one branch.

Best practices

Section titled Best practices

oneRepo provides a robust API and suite of tools to flesh out your commands. Please refer to the full API documentation for available methods, namespaces, and interfaces.

Input arguments

Section titled Input arguments

oneRepo exports a handful of builders for common input arguments and getters for file and workspace querying based on the builders’ input arguments.

commands/list-workspaces.ts

import { builders } from 'onerepo';
import type { Builder, Handler } from 'onerepo';

export const command = 'list-workspaces';

export const description = 'A basic command lists workspaces based on input arguments';

type Argv = builders.WithWorkspaces & builders.WithAffected;

export const builder: Builder<Argv> = (yargs) =>
  builders.withWorkspaces(builders.withAffected(yargs));

export const handler: Handler<Argv> = async (argv, { getWorkspaces, logger }) => {
  // Get a list of workspaces given the input arguments
  const workspaces = await getWorkspaces();
  logger.info(workspaces.map((ws) => ws.name).join('\n'));
};

1. Import the builders namespace from onerepo
2. For TypeScript, ensure you include the builder types in your arguments type definition.
3. Wrap the return value from your exported builder with the builders helpers.
4. The getters from the handler extra arguments will automatically be affected by the input arguments used.

Adding the withWorkspaces and withAffected builder composition functions to our exported builder, a few options are automatically added to our command. Looking at the --help output will describe each one of them in detail:

$ one list-workspaces --help

A basic command that shows the minimum requirements for writing commands with
oneRepo

Global:
      --dry-run        Run without actually making modifications or destructive
                       operations                     [boolean] [default: false]
  -v, --verbosity      Set the verbosity of the script output. Increase
                       verbosity with `-vvv`, `-vvvv`, or `-vvvvv`. Reduce
                       verbosity with `-v` or `--silent`    [count] [default: 2]
      --show-advanced  Pair with `--help` to show advanced options.    [boolean]
  -h, --help           Show this help screen                           [boolean]

Options:
      --affected    Select all affected workspaces. If no other inputs are
                    chosen, this will default to `true`.               [boolean]
      --staged      Use files on the git stage to calculate affected files or
                    workspaces. When unset or `--no-staged`, changes will be
                    calculated from the entire branch, since its fork point.
                                                                       [boolean]
  -a, --all         Run across all workspaces                          [boolean]
  -w, --workspaces  List of workspace names to run against               [array]

Finally, running our command, we can see list of workspaces based on those added input argument flags:

$ one my-command --workspace some-workspace --affected
 ┌ Get workspaces from inputs
 └ ✔ 101ms
 INFO workspace-a
 INFO workspace-b
■ ✔ Completed 128ms

Full API documentation

Refer to the online API documentation for a full list of helpful builders and handler getters.

Write helpful documentation

Section titled Write helpful documentation

The more explanation and context that you can provide, the better it will be for your peers using commands. Consider adding epilogues and examples along with the required description.

You can also generate Markdown documentation of the full CLI using the docgen plugin!

Logging

Section titled Logging

Do

Use the built-in logger.

Don’t

Use console.log or a third-party logger.

oneRepo provides a robust Logger to all commands and methods. This logger is responsible for tracking output and ensuring that all subprocess output is buffered and redirected appropriately for a better debugging experience.

This logger should always be used instead of directly writing to console.log or process.stdout unless you explicitly know that your output should be piped to another process (e.g. you want to write JSON to stdout).

The logger instance is primarily available in command handlers via the HandlerExtra. Logger verbosity is controlled via the global counter argument --verbosity, or -v.

export const handler: Handler = async (argv, { logger }) => {
  // -v (1)
  logger.error('This will output an error (and also set cause this run to exit with code 1)');
  logger.info('This will output an important informative message.');
  // -vv (2, default)
  logger.warn('This will output a warning');
  // -vvv (3)
  logger.log('This is log output');
  // -vvvv (4)
  logger.debug('This is extra debug information');
};

Generally speaking, it is best practice to wrap your logs in steps. This will help for better scannability and timing when debugging any issues:

export const handler: Handler = async (argv, { logger }) => {
  const step = logger.createStep('Setup');
  step.debug('do some work and write to the logger via the `step`');
  // Ensure you await the step to end so all logs are written out of the buffer
  await step.end();
};

Subprocesses

Section titled Subprocesses

Do

Use the built-in subprocessing functions like run, batch.

Don’t

Directly use Node.js APIs or third-party child_process spawning.

oneRepo includes advanced child process spawning via the run and batch functions. These async functions work like Node.js child_process.spawn, but are promise-based asynchronous functions that handle redirecting and buffering output as well as failure tracking for you. These should be used in favor of the direct Node.js builtins.

If the command you’re trying to run is installed by a third party node module through your package manager (NPM, Yarn, or pNPM), you are encouraged to use graph.packageManager.run and graph.packageManager.batch functions. These will determine the correct install path to the executable and avoid potential issues across package manager install locations.

Run single processes

Section titled Run single processes

import { run } from 'onerepo';

export const handler: Handler = async (argv) => {
  await run({
    name: 'Do some work',
    cmd: 'sleep',
    args: ['5'],
  });
};

Batching processes

Section titled Batching processes

Often it will make sense to run many things at once. The batch function handles automatic resource sharing and prevents running too many processes at once for your current machine.

import { batch } from 'onerepo';
import type { Handler, RunSpec } from 'onerepo';

export const handler: Handler = async (argv) => {
  const processes: Array<RunSpec> = [
    { name: 'Say hello', cmd: 'echo', args: ['"hello"'] },
    { name: 'Say world', cmd: 'echo', args: ['"world"'] },
  ];

  const results = await batch(processes);

  expect(results).toEqual([
    ['hello', ''],
    ['world', ''],
  ]);
};

File operations

Section titled File operations

Do

Use oneRepo’s file methods.

Don’t

Use fs from Node.

oneRepo includes many functions for reading and writing files that ensure safe operation. Developers should use these as much as possible. Check the file API documentation for a full list of available helpers.

Limiting workspaces

Section titled Limiting workspaces

Do

Limit the scope of your command to the affected workspaces.

Don’t

Always run across every workspace.

commands/my-command.ts

import { builders } from 'onerepo';

export const command = 'my-command';

export const description = 'A useful description for my command';

type Argv = builders.WithWorkspaces & builders.WithAffected;

export const builder: Builder<Argv> = (yargs) =>
  builders.withAffected(builders.withWorkspaces(yargs));

export const handler: Handler<Argv> = (argv, { getWorkspaces }) => {
  // Get a list of workspaces given the input arguments
  const workspaces = getWorkspaces();
};

By using the builders helpers, your command will automatically have extra input arguments available that help limit which workspaces will be returned from the getWorkspaces function. By default, --affected will be set to true unless you specify another option when invoking the command.

Default usage

one my-command

Run for workspaces 'foo' and 'bar' only

one my-command --workspaces foo bar

Force run against all workspaces

one my-command --all

Automated tests

Section titled Automated tests

Avoiding writing tooling that is easily mis-interpreted and prone to breaking by writing functional tests around your custom commands. The oneRepo suite includes the ability to set up a mock environment to run commands with CLI flags and assert on their behaviors within both Jest and Vitest.

To get started, install the @onerepo/test-cli package as a development dependency:

npm install --save-dev @onerepo/test-cli

commands/__tests__/my-command.test.ts

import * as oneRepo from 'onerepo';
import { getCommand } from '@onerepo/test-cli';
import * as MyCommand from '../my-command';

const { build, run } = getCommand(MyCommand);

describe('my-command', () => {
  test('can test the builder', async () => {
    const argv = await build('--arg1 --arg2=foo');

    expect(argv).toMatchObject({
      /* ... */
    });
  });

  test('can test the handler', async () => {
    vi.spyOn(oneRepo, 'run').mockResolvedValue(['', '']);
    await run('--arg1 --arg2=foo');

    expect(oneRepo.run).toHaveBeenCalledWith(
      expect.objectContaining({
        cmd: 'foo',
        args: ['...'],
      }),
    );
  });
});

More examples

Section titled More examples

Did you also know that oneRepo plugins are written nearly identical to the way commands are custom written in your monorepo? The official oneRepo plugins are the best source for up-to-date, working examples of commands.

• Determining appropriate files and default setup for a single process: @onerepo/plugin-eslint
• Batching multiple processes against affected or input workspaces: @onerepo/plugin-typescript