🏯 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 the commands with simple API and support universal runtime.
• ⚙️ Declarative configuration: Configure command modules declaratively for better organization and maintainability.
• 🛡️ Type Safe: TypeScript support with type-safe argument parsing and option resolution by args-tokens
• 🧩 Composable: Create modular sub-commands that can be composed together for complex CLIs.
• ⏳ Lazy & Async: Load command modules lazily and execute them asynchronously for better performance.
• 📜 Auto usage generation: Generate helpful usage messages automatically for your commands.
• 🎨 Custom usage generation: Customize how usage messages are generated to match your CLI’s style.
• 🌍 Internationalization: Support multiple languages with built-in i18n, locale resource lazy loading and i18n library integration.

💿 Installation

# npm
npm install --save gunshi

## pnpm
pnpm add gunshi

## yarn
yarn add gunshi

## deno
deno add jsr:@kazupon/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