kazupon/gunshi

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

What it solves

Gunshi addresses the complexity of building modern command-line interfaces. Developers often face challenges with parsing arguments, handling sub-commands, ensuring type safety, and making the CLI easy to use for both humans and automated AI agents. Gunshi provides a structured way to define commands with minimal boilerplate.

How it works

You define commands as objects that specify arguments (with types, defaults, and descriptions) and a run function that executes the command logic. Sub-commands can be added with the subCommands option. Gunshi handles argument parsing from process.argv and provides type-safe access to parsed values. It uses a pluggable system for rendering help and errors, supports internationalization for multi-language output, and can detect if the CLI is being used by an AI agent to adjust output (e.g., producing JSON). Lazy loading allows sub-commands to be loaded only when needed.

Who it’s for

It's for developers who want to create robust, maintainable CLIs. It's especially useful if you plan to make your CLI accessible to AI agents, need type safety in command arguments, or want to modularize a CLI with many sub-commands. The internationalization support makes it suitable for global tooling.

Highlights

  • Simple, declarative command definitions with type-safe parsing.
  • Built for AI agents: can output JSON and detect AI usage.
  • Composable sub-commands with shared context and lazy loading.
  • Flexible rendering: customize help, usage, and error messages.
  • Internationalization and locale-aware design.
  • Pluggable plugin system with lifecycle hooks.

Related

  • Project
  • Project
  • Project
  • Project