# Jinju

> Composable, type-safe toolkit for building Node command-line apps

Use Jinju to build a Node command-line app in TypeScript. Flags, args and commands are defined as separate values and composed into a program, and each command gets fully typed input, with help pages, error reporting and exit codes handled.

Install it with `npm install jinju`. It needs Node 22.12 or newer and has no runtime dependencies. Its types (`node_modules/jinju/dist/index.d.ts`) are the most reliable reference for the installed version.

In the examples, comments under a line show the types TypeScript infers for it, and `error TS…` comments show an intended type error.

## Table of Contents

### Introduction

- [Getting started](https://jinju.js.org/guide/getting-started.md): Install Jinju and build a first command-line app with typed flags, args and commands.

### Essentials

- [Flags](https://jinju.js.org/guide/flags.md): Named options such as --port 8080: value types, switches, modifiers (.required(), .multiple(), .default()), aliases and custom parsers.
- [Args](https://jinju.js.org/guide/args.md): Positional values such as src and dest in cp src dest: the args tuple, optional and required args, variadic .multiple() args and how values are allocated.
- [Commands](https://jinju.js.org/guide/commands.md): Commands bundle flags, args and a run handler; how they are named, what run receives, aliases and exit codes.
- [Program](https://jinju.js.org/guide/program.md): jinju() builds a program from a command tree: its options, nested commands, running it with argv and rendering help.

### Structure

- [Scopes](https://jinju.js.org/guide/scopes.md): Share flags and args across several commands with scope(), with their types flowing through to each command.
- [Dynamic segments](https://jinju.js.org/guide/dynamic-segments.md): Read a value before the command name, like a route parameter: app my-site deploy, with :name keys in the command tree.

### Values

- [Standard Schema](https://jinju.js.org/guide/schemas.md): Use any Standard Schema (zod, valibot, arktype) to parse and validate flag and arg values.
- [Environment variables](https://jinju.js.org/guide/environment-variables.md): Let any flag fall back to an environment variable with the env option, and supply variables yourself in tests.

### Output

- [Help](https://jinju.js.org/guide/help.md): The --help pages generated from your definitions, and customising them by extending HelpTemplate.
- [Errors](https://jinju.js.org/guide/errors.md): How invalid input is reported (every error at once, with exit code 1), throwing JinjuError from run, and customising output with ErrorTemplate.

### Going further

- [Testing](https://jinju.js.org/guide/testing.md): Test a CLI in-process by injecting argv, env, stdout, stderr and the exit code.
- [TypeScript](https://jinju.js.org/guide/typescript.md): The types for naming what Jinju infers: InferFlagType, InferFlags, InferArgs and more.

### API reference

- [flag](https://jinju.js.org/api/flag.md): API reference for flag: every flag and switch creator, their options and the Flag modifiers.
- [arg](https://jinju.js.org/api/arg.md): API reference for arg: every positional arg creator, their options and the Arg modifiers.
- [command & scope](https://jinju.js.org/api/command.md): API reference for command() and scope(): their config, the run context and returned values.
- [Program](https://jinju.js.org/api/program.md): API reference for jinju() and Program: the program config, run() and help(), and packageVersion().
- [Help](https://jinju.js.org/api/help.md): API reference for HelpTemplate and the help data it renders.
- [Errors](https://jinju.js.org/api/errors.md): API reference for ErrorTemplate, JinjuError and every error class Jinju throws.
- [Types](https://jinju.js.org/api/types.md): API reference for every exported type, including the inference types.

### Other

- [Changelog](https://jinju.js.org/changelog.md): Every notable change to Jinju, by release.