> ## Documentation Index
> Fetch the complete documentation index at: https://narrator.ami.rip/llms.txt
> Use this file to discover all available pages before exploring further.

# @usenarrator/cli

> The narrator command: narrate files, directories, globs and git diffs from the terminal.

```bash theme={null}
npm install --global @usenarrator/cli
```

The CLI needs Node 22.17 or newer, or Bun. It depends on the parser and every plugin, so nothing else needs installing.

```text theme={null}
narrator <file|dir|glob>...      narrate files (reads stdin when none are given)
narrator diff <base>..<head>     narrate a git change set (omit <head> for the working tree)
```

## Narrating files

Each argument can be a file, a directory or a glob. Directories are searched recursively for `.ts`, `.tsx`, `.js`, `.jsx`, `.mjs` and `.cjs` files, skipping `.d.ts` files. With one file, the CLI prints its English. With several, it prints each file's path followed by its English, indented. Problems such as syntax errors are printed to standard error, and the English is still printed.

## Generated and vendored files

Inside directories and globs, and in diffs, the CLI skips code nobody wrote by hand:

* dependencies, under `node_modules`, which are never searched
* build output, under `dist`, `.next`, `.nuxt`, `.output`, `.svelte-kit`, `.vercel`, `.turbo`, `.cache` and `coverage`, and JavaScript under `build` or `out`
* vendored code, under `vendor` and `.yarn`
* lockfiles, `.pnp.cjs`, and `*.min.js`, `*.bundle.js` and `*.chunk.js` files
* files that `.gitattributes` marks `linguist-generated` or `linguist-vendored`
* files that start with a generated-code banner such as `// Code generated by X. DO NOT EDIT.` or `@generated`
* minified files, recognised by very long lines

When narrating files, folders like `dist` are passed over silently, and the CLI prints to standard error how many other files it skipped because of their attributes or content. In a diff, each skipped file gets one line, such as `.yarn/releases/yarn.cjs [deleted, skipped: vendored]`. A file you name directly is always narrated, and `--include-generated` turns the skipping off.

## Narrating diffs

`narrator diff <base>..<head>` compares two revisions, `narrator diff <base>...<head>` compares `head` with its merge base, and `narrator diff <base>` compares a revision with the working tree. Renamed files are detected with git's rename detection, and moved or renamed declarations are matched across files. See [Units and diffs](/concepts/units-and-diffs).

A file that can't be read is listed with a line starting with `!` that says why, for example `! Syntax error on line 12: Unexpected token`, and the rest of the diff is narrated as usual. `--json` output includes the same information as `skipped` and `problems` on each file.

## Options

| Option | Description |
| - | - |
| `--plugins <list>` | A comma-separated list of plugins to load, or `all` or `none`. By default, plugins are chosen from the `package.json` files that apply to the narrated files, and every plugin is loaded when no manifest lists a known library. |
| `--locale <id>` | The output language. `en` is built in, and other ids are loaded from `@usenarrator/locale-<id>`. |
| `--include-generated` | Also narrates generated, vendored, minified and build files. |
| `--plain`, `--ansi`, `--json`, `--html` | The output format. The default is `--ansi` in a terminal and `--plain` otherwise, and `NO_COLOR` turns colour off. `--json` prints lines with their depth, kind, text and source offsets, plus each file's `problems`, and `--html` prints a standalone page. |
| `-h`, `--help` | Prints usage. |

## Plugin names

| Name | Detected from |
| - | - |
| `zod` | `zod` |
| `valibot` | `valibot` |
| `arktype` | `arktype` |
| `testing` | `vitest`, `jest`, `@jest/globals`, `@types/jest`, `bun-types`, `@types/bun` |
| `decimal` | `decimal.js`, `decimal.js-light` |
| `drizzle` | `drizzle-orm` |
| `prisma` | `prisma`, `@prisma/client` |
| `kysely` | `kysely` |
| `sql` | `postgres`, `pg`, `better-sqlite3`, `@neondatabase/serverless`, `kysely`, `slonik`, `@prisma/client`, `mysql2`, Bun's types |
| `effect` | `effect`, `@effect/*` |
| `better-auth` | `better-auth` |
| `stripe` | `stripe` |
| `autumn-js` | `autumn-js`, `@useautumn/sdk` |
| `hono` | `hono` |
| `elysia` | `elysia` |
| `express` | `express` |
| `fastify` | `fastify` |
| `trpc` | `@trpc/*` |
| `ai-sdk` | `ai`, `@ai-sdk/*` |
| `react` | `react`, `react-dom` (skipped when `nextjs` is detected, since it includes React) |
| `nextjs` | `next` |
| `tanstack-query` | `@tanstack/*-query` |
| `bullmq` | `bullmq`, `bullmq-pro` |
| `inngest` | `inngest` |
| `trigger-dev` | `@trigger.dev/*` |
| `temporal` | `@temporalio/*` |

## From code

The package also exports `main(argv, { extraPlugins })`, which runs the CLI and returns an exit code, `run({ argv, isTTY, extraPlugins, warn })`, which returns the output as a string, and `detectPlugins(dependencyNames)`, `loadPlugins(names)` and `PLUGINS` for building the same plugin selection yourself. `extraPlugins` adds your own codebase plugins after the detected ones, which is how to give the CLI your team's vocabulary:

```js narrate.mjs theme={null}
#!/usr/bin/env node
import { main } from "@usenarrator/cli";
import { myCodebase } from "./narrator-plugin.mjs";

process.exitCode = await main(process.argv.slice(2), { extraPlugins: [myCodebase()] });
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.