🏯 Gunshi

Gunshi is a JavaScript command-line library, your strategist for CLIs that people and AI agents use.

[!TIP]
gunshi (軍師) is a position in ancient Japanese samurai battle in which a samurai devised strategies and gave orders. That name is inspired by the word "command".

Features

Gunshi is designed to simplify the creation of modern command-line interfaces:

📏 Simple & AI agent friendly: Commands with simple APIs, output as JSON, and detects AI agents.
⚙️ Declarative & Type Safe: Configure commands declaratively with full TypeScript support and type-safe argument parsing by args-tokens
🧩 Composable & Lazy: Create modular sub-commands with context sharing and lazy loading for better performance.
🎨 Flexible Rendering: Customize usage generation, validation errors, and help messages with pluggable renderers.
🌍 Internationalization: Built with global users in mind, featuring locale-aware design, resource management, and multi-language support.
🔌 Pluggable: Extensible plugin system with dependency management and lifecycle hooks for modular CLI development.

Installation

# npm
npm install --save gunshi

## pnpm
pnpm add gunshi

## yarn
yarn add gunshi

## bun
bun add gunshi

Usage

import { cli } from 'gunshi'

// define a command with declarative configuration, using commandable object
const command = {
  name: 'greet',
  description: 'A greeting command',
  args: {
    name: {
      type: 'string',
      short: 'n',
      description: 'Name to greet'
    },
    greeting: {
      type: 'string',
      short: 'g',
      default: 'Hello',
      description: 'Greeting to use (default: "Hello")'
    },
    times: {
      type: 'number',
      short: 't',
      default: 1,
      description: 'Number of times to repeat the greeting (default: 1)'
    }
  },
  run: ctx => {
    const { name = 'World', greeting, times } = ctx.values
    for (let i = 0; i < times; i++) {
      console.log(`${greeting}, ${name}!`)
    }
  }
}

// run a command that is defined above
// (the 3rd argument of `cli` is the command option)
await cli(process.argv.slice(2), command, {
  name: 'my-app',
  version: '1.0.0',
  description: 'My CLI application'
})

Sub-commands are given with subCommands, keyed by their names:

import { cli, define } from 'gunshi'

const add = define({
  name: 'add',
  description: 'Add an item',
  args: {
    title: { type: 'positional', description: 'The title of the item' }
  },
  run: ctx => console.log(`Added: ${ctx.values.title}`)
})

const list = define({
  name: 'list',
  description: 'List the items',
  run: () => console.log('No items')
})

const main = define({
  name: 'todo',
  description: 'Manage the items'
})

// `todo add milk`, `todo list` and `todo --help`
await cli(process.argv.slice(2), main, {
  version: '1.0.0',
  subCommands: { add, list }
})

subCommands can also be an array of commands ([add, list]), and can also be given on the main command (define({ name: 'todo', subCommands: { add, list } })).

About more details and usage, see documentations

Showcases

pnpmc: PNPM Catalogs Tooling
sourcemap-publisher: A tool to publish sourcemaps externally and rewrite sourcemap URLs at pre-publish time
curxy: An proxy worker for using ollama in cursor
SiteMCP: Fetch an entire site and use it as an MCP Server
ccusage: A CLI tool for analyzing Claude Code usage from local JSONL files
varlock: Enhanced .env file loader, using @decorator style comments to add validation, type-safety, and more

Contributing guidelines

If you are interested in contributing to gunshi, I highly recommend checking out the contributing guidelines here. You'll find all the relevant information such as how to make a PR, how to setup development) etc., there.

Credits

This project is inspired and powered by:

citty, created by UnJS team and contributors
ordana, createdy by sapphi-red, inspired documentation generation
cline and claude 3.7 sonnet, examples and docs is generated

Thank you!

License

MIT

gunshi