@usenarrator/cli

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.

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. 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:

narrate.mjs

#!/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()] });

Packages

Tools

Narrating files

Generated and vendored files

Narrating diffs

Options

Plugin names

From code

​Narrating files

​Generated and vendored files

​Narrating diffs

​Options

​Plugin names

​From code

Narrating files

Generated and vendored files

Narrating diffs

Options

Plugin names

From code