\n\n[![Version][npm-version-src]][npm-version-href]\n[![CI][ci-src]][ci-href]\n[![InstallSize][install-size-src]][install-size-src]\n[![JSR][jsr-src]][jsr-href]\n\nGunshi is a modern javascript command-line library\n\n\n\n> [!TIP]\n> 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\".\n\n\n\n## Features\n\nGunshi is designed to simplify the creation of modern command-line interfaces:\n\n- 📏 **Simple & Universal**: Run commands with simple API and support for universal runtime (Node.js, Deno, Bun).\n- ⚙️ **Declarative & Type Safe**: Configure commands declaratively with full TypeScript support and type-safe argument parsing by [args-tokens](https://github.com/kazupon/args-tokens)\n- 🧩 **Composable & Lazy**: Create modular sub-commands with context sharing and lazy loading for better performance.\n- 🎨 **Flexible Rendering**: Customize usage generation, validation errors, and help messages with pluggable renderers.\n- 🌍 **Internationalization**: Built with global users in mind, featuring locale-aware design, resource management, and multi-language support.\n- 🤖 **Agent-aware**: Detect AI coding-agent environments through the stable [`gunshi/agent`](https://gunshi.dev/guide/advanced/ai-agent-detection) utility without changing CLI behavior automatically.\n- 🔌 **Pluggable**: Extensible plugin system with dependency management and lifecycle hooks for modular CLI development.\n\n## Installation\n\n```sh\n# npm\nnpm install --save gunshi\n\n## pnpm\npnpm add gunshi\n\n## yarn\nyarn add gunshi\n\n## deno\ndeno add jsr:@gunshi/gunshi\n\n## bun\nbun add gunshi\n```\n\n## Usage\n\n```js\nimport { cli } from 'gunshi'\n\n// define a command with declarative configuration, using commandable object\nconst command = {\n name: 'greet',\n description: 'A greeting command',\n args: {\n name: {\n type: 'string',\n short: 'n',\n description: 'Name to greet'\n },\n greeting: {\n type: 'string',\n short: 'g',\n default: 'Hello',\n description: 'Greeting to use (default: \"Hello\")'\n },\n times: {\n type: 'number',\n short: 't',\n default: 1,\n description: 'Number of times to repeat the greeting (default: 1)'\n }\n },\n run: ctx => {\n const { name = 'World', greeting, times } = ctx.values\n for (let i = 0; i < times; i++) {\n console.log(`${greeting}, ${name}!`)\n }\n }\n}\n\n// run a command that is defined above\n// (the 3rd argument of `cli` is the command option)\nawait cli(process.argv.slice(2), command, {\n name: 'my-app',\n version: '1.0.0',\n description: 'My CLI application'\n})\n```\n\nAbout more details and usage, see [documentations](https://gunshi.dev)\n\n## Showcases\n\n- [pnpmc](https://github.com/kazupon/pnpmc): PNPM Catalogs Tooling\n- [sourcemap-publisher](https://github.com/es-tooling/sourcemap-publisher): A tool to publish sourcemaps externally and rewrite sourcemap URLs at pre-publish time\n- [curxy](https://github.com/ryoppippi/curxy): An proxy worker for using ollama in cursor\n- [SiteMCP](https://github.com/ryoppippi/sitemcp): Fetch an entire site and use it as an MCP Server\n- [ccusage](https://github.com/ryoppippi/ccusage): A CLI tool for analyzing Claude Code usage from local JSONL files\n- [varlock](https://github.com/dmno-dev/varlock): Enhanced .env file loader, using @decorator style comments to add validation, type-safety, and more\n\n## Contributing guidelines\n\nIf you are interested in contributing to `gunshi`, I highly recommend checking out [the contributing guidelines](/CONTRIBUTING.md) here. You'll find all the relevant information such as [how to make a PR](/CONTRIBUTING.md#pull-request-guidelines), [how to setup development](/CONTRIBUTING.md#development-setup)) etc., there.\n\n## Credits\n\nThis project is inspired and powered by:\n\n- [`citty`](https://github.com/unjs/citty), created by [UnJS team](https://github.com/unjs) and contributors\n- [`ordana`](https://github.com/sapphi-red/ordana), createdy by [sapphi-red](https://github.com/sapphi-red), inspired documentation generation\n- cline and claude 3.7 sonnet, examples and docs is generated\n\nThank you!\n\n## Sponsors\n\nThe development of Gunshi is supported by my OSS sponsors!\n\n
![\"logo\"](\"./assets/logo.png\"){kind=logo}
\n![\"sponsor\"](\"https://cdn.jsdelivr.net/gh/kazupon/sponsors/sponsors.svg\")
\n \n