How to create a CLI with subcommands?

[real34]

Hi,

I have developed a bunch of scripts that sits in local folders on my machine:

~/bin
├── generic.mjs
├── topic
│   ├── foo.mjs
│   ├── bar.mjs

For now I always use them as ~/bin/generic.mjs or ~/bin/topic/foo.mjs.

I wanted to know what would be the recommended way to group everything related to a specific topic under a single CLI entrypoint, so that I could do something like:

~/bin/topic --help # lists all commands
~/bin/topic foo --foo=bar # spawn foo.mjs by propagating all params
~/bin/topic bar

Are there any examples of such patterns? Is it something that zx wants to solve, or isn't it in its scope?

Bonus: how could I then share these scripts with my coworkers? (i.e: have a shared Git repo we could pull and add to our path)

[agammann]

A small dispatcher can use Node to select a known script, then invoke zx's CLI with the remaining arguments. Put this beside foo.mjs and bar.mjs as topic.mjs:

#!/usr/bin/env node
import { spawn } from 'node:child_process';
import { createRequire } from 'node:module';
import { fileURLToPath } from 'node:url';

const require = createRequire(import.meta.url);
const commands = new Map([
  ['foo', new URL('./foo.mjs', import.meta.url)],
  ['bar', new URL('./bar.mjs', import.meta.url)],
]);
const [command, ...args] = process.argv.slice(2);

if (!command || command === '--help') {
  console.log('Usage: topic <foo|bar> [arguments...]');
} else if (!commands.has(command)) {
  console.error(`Unknown command: ${command}`);
  process.exitCode = 1;
} else {
  const child = spawn(process.execPath, [
    require.resolve('zx/cli'),
    fileURLToPath(commands.get(command)),
    ...args,
  ], { stdio: 'inherit' });
  child.on('error', error => {
    console.error(error.message);
    process.exitCode = 1;
  });
  child.on('exit', code => { process.exitCode = code ?? 1; });
}

Then run node topic.mjs --help or node topic.mjs foo --foo=bar. The argument array is forwarded without constructing another shell command, and each selected script is still run by zx. The script paths are resolved relative to the dispatcher rather than the caller's current directory.

I tested help, an unknown command, both subcommands, a forwarded argument containing spaces, and a child exit code with zx 8.8.4 / Node 24.19.0. For sharing, commit this directory plus package.json/lockfile with zx as a dependency. You can expose topic.mjs through your package's bin field; teammates still need Node and the installed dependencies. zx CLI.