Multi-Command CLIs

Create router CLIs with multiple subcommands using .command() chaining

Multi-command CLIs act as routers, directing execution to different handlers based on the subcommand. This is the pattern used by tools like git, docker, and npm.

When to Use Multi-Command Pattern

Use this pattern when your CLI:

• Provides multiple related operations
• Needs a clean namespace for different actions
• Benefits from command-specific help

Examples: git commit, docker build, npm install

Creating a Router CLI

1. Create CLI without run
2. Omit the run property to create a router:
3. import { Cli, z } from 'incur'
   
   const cli = Cli.create('my-cli', {
     description: 'My CLI',
   })
   

4. Chain .command() calls
5. Register subcommands using .command(). Each command is independent:
6. cli
     .command('status', {
       description: 'Show repo status',
       run() {
         return { clean: true }
       },
     })
     .command('install', {
       description: 'Install a package',
       args: z.object({
         package: z.string().optional().describe('Package name'),
       }),
       options: z.object({
         saveDev: z.boolean().optional().describe('Save as dev dependency'),
       }),
       alias: { saveDev: 'D' },
       run(c) {
         return { added: 1, packages: 451 }
       },
     })
     .serve()
   

7. Run subcommands
8. my-cli status
   # → clean: true
   
   my-cli install express -D
   # → added: 1
   # → packages: 451
   

Command Organization

Each command is self-contained with its own args, options, and handler:

Cli.create('repo', {
  description: 'Repository management',
})
  .command('clone', {
    description: 'Clone a repository',
    args: z.object({
      url: z.string().describe('Repository URL'),
    }),
    options: z.object({
      depth: z.coerce.number().optional().describe('Clone depth'),
      branch: z.string().optional().describe('Branch to clone'),
    }),
    run(c) {
      return {
        cloned: c.args.url,
        branch: c.options.branch ?? 'main',
      }
    },
  })
  .command('list', {
    description: 'List repositories',
    options: z.object({
      limit: z.coerce.number().default(10).describe('Number of repos to show'),
      private: z.boolean().optional().describe('Include private repos'),
    }),
    run(c) {
      return {
        repos: ['repo1', 'repo2'],
        count: 2,
        limit: c.options.limit,
      }
    },
  })
  .command('delete', {
    description: 'Delete a repository',
    args: z.object({
      name: z.string().describe('Repository name'),
    }),
    options: z.object({
      force: z.boolean().optional().describe('Skip confirmation'),
    }),
    run(c) {
      if (!c.options.force) {
        return c.error({
          code: 'CONFIRMATION_REQUIRED',
          message: 'Use --force to confirm deletion',
        })
      }
      return { deleted: c.args.name }
    },
  })
  .serve()

Help Text Generation

Help is automatically generated for the router and each command.

Router Help

my-cli --help
# my-cli – My CLI
#
# Usage: my-cli <command>
#
# Commands:
#   install  Install a package
#   status   Show repo status
#
# Built-in Commands:
#   completions  Generate shell completion script
#   mcp add      Register as an MCP server
#   skills add   Sync skill files to your agent
#
# Global Options:
#   --format <toon|json|yaml|md|jsonl>  Output format
#   --help                              Show help
#   --llms                              Print LLM-readable manifest
#   --mcp                               Start as MCP stdio server
#   --verbose                           Show full output envelope
#   --version                           Show version

Command-Specific Help

my-cli install --help
# my-cli install – Install a package
#
# Usage: my-cli install [package] [options]
#
# Arguments:
#   package  Package name (optional)
#
# Options:
#   -D, --saveDev  Save as dev dependency
#
# Global Options:
#   --format <toon|json|yaml|md|jsonl>  Output format
#   --help                              Show help
#   --json                              Shorthand for --format json
#   --verbose                           Show full output envelope

Multiple Arguments Per Command

Each command can have its own argument schema:

Cli.create('file', {
  description: 'File operations',
})
  .command('copy', {
    description: 'Copy a file',
    args: z.object({
      source: z.string().describe('Source file'),
      destination: z.string().describe('Destination file'),
    }),
    run(c) {
      return { copied: true, from: c.args.source, to: c.args.destination }
    },
  })
  .command('read', {
    description: 'Read a file',
    args: z.object({
      path: z.string().describe('File path'),
    }),
    options: z.object({
      lines: z.coerce.number().optional().describe('Number of lines to read'),
    }),
    run(c) {
      return { path: c.args.path, content: '...' }
    },
  })
  .serve()

file copy input.txt output.txt
# → copied: true
# → from: input.txt
# → to: output.txt

file read data.txt --lines 10
# → path: data.txt
# → content: ...

Complete Multi-Command Example

Here’s a complete package manager CLI:

index.ts

import { Cli, z } from 'incur'

Cli.create('pkg', {
  description: 'Package manager',
  version: '1.0.0',
})
  .command('install', {
    description: 'Install packages',
    args: z.object({
      packages: z.array(z.string()).optional().describe('Packages to install'),
    }),
    options: z.object({
      dev: z.boolean().optional().describe('Install as dev dependencies'),
      global: z.boolean().optional().describe('Install globally'),
    }),
    alias: { dev: 'D', global: 'g' },
    run(c) {
      const packages = c.args.packages ?? []
      const count = packages.length || 1
      return {
        installed: count,
        dev: c.options.dev ?? false,
        global: c.options.global ?? false,
      }
    },
  })
  .command('uninstall', {
    description: 'Uninstall packages',
    args: z.object({
      package: z.string().describe('Package to uninstall'),
    }),
    run(c) {
      return { removed: c.args.package }
    },
  })
  .command('list', {
    description: 'List installed packages',
    options: z.object({
      depth: z.coerce.number().default(0).describe('Dependency depth'),
      json: z.boolean().optional().describe('Output as JSON'),
    }),
    run(c) {
      return {
        packages: [
          { name: 'express', version: '4.18.0' },
          { name: 'zod', version: '3.22.0' },
        ],
        depth: c.options.depth,
      }
    },
  })
  .command('update', {
    description: 'Update packages',
    args: z.object({
      package: z.string().optional().describe('Specific package to update'),
    }),
    options: z.object({
      latest: z.boolean().optional().describe('Update to latest version'),
    }),
    run(c) {
      return {
        updated: c.args.package ?? 'all',
        latest: c.options.latest ?? false,
      }
    },
  })
  .serve()

Usage Examples

# Install all dependencies
pkg install
# → installed: 1
# → dev: false
# → global: false

# Install specific packages as dev dependencies
pkg install typescript vitest -D
# → installed: 2
# → dev: true
# → global: false

# List installed packages
pkg list --depth 2
# → packages[2]{name,version}:
# →   express,4.18.0
# →   zod,3.22.0
# → depth: 2

# Update a specific package
pkg update express --latest
# → updated: express
# → latest: true

# Get help for a command
pkg install --help

Type Safety

All arguments and options are fully typed:

Cli.create('calc', {})
  .command('add', {
    args: z.object({
      a: z.coerce.number(),
      b: z.coerce.number(),
    }),
    run(c) {
      // c.args.a and c.args.b are typed as `number`
      return { result: c.args.a + c.args.b }
    },
  })
  .serve()

The .command() method returns the same CLI instance, so you can chain as many commands as you need. The type system tracks all registered commands for features like CTAs.

Router vs Single-Command

Feature	Router (no run)	Single-Command (with run)
Subcommands	✓ Yes	✗ No
Root handler	✗ No	✓ Yes
Use case	Multi-purpose tool	Single-purpose utility
Help format	Lists commands	Shows usage
Example	git, docker	grep, curl

Don’t mix patterns! A router CLI (without run) is meant to route to subcommands. If you need both a root handler and subcommands, use sub-commands instead.