Skip to content
Back to search

gunshi

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

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked yesterday

Check it deeper on your machine

It has changed since its scan on 18 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/kazupon/gunshi with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/kazupon/gunshi'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/kazupon--gunshi/badge.svg)](/listings/kazupon--gunshi)

HTML

<a href="/listings/kazupon--gunshi"><img src="/api/listings/kazupon--gunshi/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# npm
npm install --save gunshi

## pnpm
pnpm add gunshi

## yarn
yarn add gunshi

## bun
bun add gunshi

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 170 lines
  1. <p align="center">
  2. <img alt="logo" width="196" src="./assets/logo.png">
  3. </p>
  4. <h1 align="center">🏯 Gunshi</h1>
  5. [![Version][npm-version-src]][npm-version-href]
  6. [![CI][ci-src]][ci-href]
  7. [![InstallSize][install-size-src]][install-size-src]
  8. Gunshi is a JavaScript command-line library, your strategist for CLIs that people and AI agents use.
  9. <!-- eslint-disable markdown/no-missing-label-refs -->
  10. > [!TIP]
  11. > 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".
  12. <!-- eslint-enable markdown/no-missing-label-refs -->
  13. ## Features
  14. Gunshi is designed to simplify the creation of modern command-line interfaces:
  15. - 📏 **Simple & AI agent friendly**: Commands with simple APIs, output as JSON, and detects AI agents.
  16. - ⚙️ **Declarative & Type Safe**: Configure commands declaratively with full TypeScript support and type-safe argument parsing by [args-tokens](https://github.com/kazupon/args-tokens)
  17. - 🧩 **Composable & Lazy**: Create modular sub-commands with context sharing and lazy loading for better performance.
  18. - 🎨 **Flexible Rendering**: Customize usage generation, validation errors, and help messages with pluggable renderers.
  19. - 🌍 **Internationalization**: Built with global users in mind, featuring locale-aware design, resource management, and multi-language support.
  20. - 🔌 **Pluggable**: Extensible plugin system with dependency management and lifecycle hooks for modular CLI development.
  21. ## Installation
  22. ```sh
  23. # npm
  24. npm install --save gunshi
  25. ## pnpm
  26. pnpm add gunshi
  27. ## yarn
  28. yarn add gunshi
  29. ## bun
  30. bun add gunshi
  31. ```
  32. ## Usage
  33. ```js
  34. import { cli } from 'gunshi'
  35. // define a command with declarative configuration, using commandable object
  36. const command = {
  37. name: 'greet',
  38. description: 'A greeting command',
  39. args: {
  40. name: {
  41. type: 'string',
  42. short: 'n',
  43. description: 'Name to greet'
  44. },
  45. greeting: {
  46. type: 'string',
  47. short: 'g',
  48. default: 'Hello',
  49. description: 'Greeting to use (default: "Hello")'
  50. },
  51. times: {
  52. type: 'number',
  53. short: 't',
  54. default: 1,
  55. description: 'Number of times to repeat the greeting (default: 1)'
  56. }
  57. },
  58. run: ctx => {
  59. const { name = 'World', greeting, times } = ctx.values
  60. for (let i = 0; i < times; i++) {
  61. console.log(`${greeting}, ${name}!`)
  62. }
  63. }
  64. }
  65. // run a command that is defined above
  66. // (the 3rd argument of `cli` is the command option)
  67. await cli(process.argv.slice(2), command, {
  68. name: 'my-app',
  69. version: '1.0.0',
  70. description: 'My CLI application'
  71. })
  72. ```
  73. Sub-commands are given with `subCommands`, keyed by their names:
  74. ```js
  75. import { cli, define } from 'gunshi'
  76. const add = define({
  77. name: 'add',
  78. description: 'Add an item',
  79. args: {
  80. title: { type: 'positional', description: 'The title of the item' }
  81. },
  82. run: ctx => console.log(`Added: ${ctx.values.title}`)
  83. })
  84. const list = define({
  85. name: 'list',
  86. description: 'List the items',
  87. run: () => console.log('No items')
  88. })
  89. const main = define({
  90. name: 'todo',
  91. description: 'Manage the items'
  92. })
  93. // `todo add milk`, `todo list` and `todo --help`
  94. await cli(process.argv.slice(2), main, {
  95. version: '1.0.0',
  96. subCommands: { add, list }
  97. })
  98. ```
  99. `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 } })`).
  100. About more details and usage, see [documentations](https://gunshi.dev)
  101. ## Showcases
  102. - [pnpmc](https://github.com/kazupon/pnpmc): PNPM Catalogs Tooling
  103. - [sourcemap-publisher](https://github.com/es-tooling/sourcemap-publisher): A tool to publish sourcemaps externally and rewrite sourcemap URLs at pre-publish time
  104. - [curxy](https://github.com/ryoppippi/curxy): An proxy worker for using ollama in cursor
  105. - [SiteMCP](https://github.com/ryoppippi/sitemcp): Fetch an entire site and use it as an MCP Server
  106. - [ccusage](https://github.com/ryoppippi/ccusage): A CLI tool for analyzing Claude Code usage from local JSONL files
  107. - [varlock](https://github.com/dmno-dev/varlock): Enhanced .env file loader, using @decorator style comments to add validation, type-safety, and more
  108. ## Contributing guidelines
  109. If 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.
  110. ## Credits
  111. This project is inspired and powered by:
  112. - [`citty`](https://github.com/unjs/citty), created by [UnJS team](https://github.com/unjs) and contributors
  113. - [`ordana`](https://github.com/sapphi-red/ordana), createdy by [sapphi-red](https://github.com/sapphi-red), inspired documentation generation
  114. - cline and claude 3.7 sonnet, examples and docs is generated
  115. Thank you!
  116. ## Sponsors
  117. The development of Gunshi is supported by my OSS sponsors!
  118. <p align="center">
  119. <a href="https://cdn.jsdelivr.net/gh/kazupon/sponsors/sponsors.svg">
  120. <img alt="sponsor" src='https://cdn.jsdelivr.net/gh/kazupon/sponsors/sponsors.svg'/>
  121. </a>
  122. </p>
  123. ## License
  124. [MIT](http://opensource.org/licenses/MIT)
  125. <!-- Badges -->
  126. [npm-version-src]: https://img.shields.io/npm/v/gunshi?style=flat
  127. [npm-version-href]: https://npmjs.com/package/gunshi
  128. [install-size-src]: https://pkg-size.dev/badge/install/72346
  129. [ci-src]: https://github.com/kazupon/gunshi/actions/workflows/ci.yml/badge.svg
  130. [ci-href]: https://github.com/kazupon/gunshi/actions/workflows/ci.yml

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.