🏯 Gunshi

Gunshi is a modern javascript command-line library

[!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 & Universal: Run commands with simple API and support for universal runtime (Node.js, Deno, Bun).
• ⚙️ 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.
• 🤖 Agent-aware: Detect AI coding-agent environments through the stable gunshi/agent utility without changing CLI behavior automatically.
• 🔌 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

## deno
deno add jsr:@gunshi/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'
})

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!

Sponsors

The development of Gunshi is supported by my OSS sponsors!

License

MIT