# CLI

> narro new, dev, build, export, import, bundle, preview, themes

```bash
npx @getnarro/cli <command>
```

Install it globally (`npm i -g @getnarro/cli`) and the binary is `narro`.

> `npx narro` resolves an unrelated package on npm. Use `npx @getnarro/cli`, or
> install globally and call `narro`.

## Commands

<!-- generated:cli-commands -->
| Command | What it does |
| --- | --- |
| `narro analyze-slides-for-components` | Analyze presentation slides to identify needed shared-ui components |
| `narro build [file]` | Build for production (pass a .md file for markdown mode) |
| `narro bundle` | Bundle presentation into a single self-contained HTML file |
| `narro capture-website <url>` | Capture a full-page screenshot of a website |
| `narro check <file|dir>` | Validate a markdown deck, or measure built output with --fit |
| `narro comments` | Manage slide comments |
| `narro create [project-name]` | Create a new Narro presentation project |
| `narro create-template-from-screenshots [template-name]` | Generate a template from presentation screenshots using AI |
| `narro dev [file]` | Start development server (pass a .md file for markdown mode) |
| `narro export [file]` | Export presentation to static files, PPTX, or Google Slides |
| `narro fmt <file>` | Normalise a deck's whitespace and frontmatter without changing what it renders |
| `narro import <source>` | Import presentation from PowerPoint or Google Slides |
| `narro new <file>` | Scaffold a starter markdown deck |
| `narro preview` | Preview built presentation |
| `narro themes` | Browse and apply themes from the marketplace |
<!-- /generated:cli-commands -->

## Reference

Generated from the command tree, so it cannot disagree with `narro --help`.

<!-- generated:cli-reference -->
### `narro analyze-slides-for-components`

Analyze presentation slides to identify needed shared-ui components

| Option | For |
| --- | --- |
| `-d, --screenshots-dir <dir>` | Directory containing screenshot files |
| `-s, --screenshots <paths...>` | Screenshot file paths |
| `-o, --output <file>` | Output markdown file |
| `-p, --provider <provider>` | AI provider (openai or claude) |
| `-m, --model <model>` | AI model to use |

### `narro build [file]`

Build for production (pass a .md file for markdown mode)

| Option | For |
| --- | --- |
| `-o, --outDir <dir>` | output directory |
| `--base <path>` | base path for deployment |
| `--no-fit` | skip the overflow measurement after building |

### `narro bundle`

Bundle presentation into a single self-contained HTML file

| Option | For |
| --- | --- |
| `-o, --output <filename>` | output filename |
| `--minify` | minify output for smaller file size |
| `--inline-assets` | inline images as base64 (default: false) |
| `--check-size` | warn if output exceeds email attachment limit (~25MB) |

### `narro capture-website <url>`

Capture a full-page screenshot of a website

| Option | For |
| --- | --- |
| `-o, --output <path>` | Output file path (default: screenshot.png) |
| `-f, --full-page` | Capture full page (scrollable content) |
| `-w, --width <number>` | Viewport width in pixels |
| `-h, --height <number>` | Viewport height in pixels |
| `-d, --delay <number>` | Delay before screenshot in milliseconds |

### `narro check <file|dir>`

Validate a markdown deck, or measure built output with --fit

| Option | For |
| --- | --- |
| `--strict` | treat warnings as errors |
| `--render` | print what each slide renders — elements, classes, and text |
| `--fit` | render the deck in a headless browser and report slides whose content overflows |
| `--fit-if-available` | like --fit, but only warn when no browser is installed |
| `--render-full` | like --render, but print long text and large props in full |

### `narro comments`

Manage slide comments

### `narro create [project-name]`

Create a new Narro presentation project

| Option | For |
| --- | --- |
| `-t, --template <template>` | Template to use (minimal, corporate, developer, creative, bold-statement, visual-story, data-narrative, startup-pitch, tech-conference, template0, markdown-minimal, markdown-app, markdown-docs) |
| `-m, --mode <mode>` | Presentation mode: react (default) or markdown |
| `--skip-install` | Skip npm install |
| `-y, --yes` | Accept the defaults for anything not given; never prompt |
| `--force` | Scaffold into a directory that already has files in it |
| `--list` | List every template with what it is, and exit |

### `narro create-template-from-screenshots [template-name]`

Generate a template from presentation screenshots using AI

| Option | For |
| --- | --- |
| `-s, --screenshots <paths...>` | Screenshot file paths |
| `-o, --output <dir>` | Output directory |
| `-p, --provider <provider>` | AI provider (openai or claude) |
| `-m, --model <model>` | AI model to use |

### `narro dev [file]`

Start development server (pass a .md file for markdown mode)

| Option | For |
| --- | --- |
| `-p, --port <number>` | port to use |
| `--host` | expose to network |
| `-o, --open` | open browser on startup |
| `--no-open` | do not open the browser (markdown mode) |
| `--theme <name>` | theme override (markdown mode) |

### `narro export [file]`

Export presentation to static files, PPTX, or Google Slides

| Option | For |
| --- | --- |
| `-o, --outDir <dir>` | output directory for HTML export |
| `--pdf` | export to PDF (requires Playwright) |
| `--png` | export slides as PNG images (requires Playwright) |
| `--to <format>` | export format: pptx, google-slides |
| `--output-path <path>` | output file path for PPTX export |
| `--include-notes` | include speaker notes in export |
| `--include-animations` | include animations in export |
| `--settle <ms>` | milliseconds to let a slide's animations finish before capturing (default: 4000) |
| `--input-path <path>` | path to presentation project |
| `--template-path <path>` | PowerPoint template file (.potx or .pptx) to apply |
| `--template-id <id>` | Google Slides template presentation ID to copy from |
| `--google-client-id <id>` | Google OAuth client ID |
| `--google-client-secret <secret>` | Google OAuth client secret |
| `--google-refresh-token <token>` | Google OAuth refresh token |

### `narro fmt <file>`

Normalise a deck's whitespace and frontmatter without changing what it renders

| Option | For |
| --- | --- |
| `--check` | report whether the deck is formatted, and exit non-zero if not |

### `narro import <source>`

Import presentation from PowerPoint or Google Slides

| Option | For |
| --- | --- |
| `--from <source>` | import source: pptx, google-slides |
| `-o, --output-dir <dir>` | output directory for imported project |
| `--preserve-styles` | preserve original styles |
| `--convert-animations` | convert animations |
| `--google-client-id <id>` | Google OAuth client ID |
| `--google-client-secret <secret>` | Google OAuth client secret |
| `--google-refresh-token <token>` | Google OAuth refresh token |

### `narro new <file>`

Scaffold a starter markdown deck

### `narro preview`

Preview built presentation

| Option | For |
| --- | --- |
| `-p, --port <number>` | port to use |
| `--host` | expose to network |
| `-o, --open` | open browser on startup |
| `-d, --outDir <dir>` | serve a directory of built output directly |

### `narro themes`

Browse and apply themes from the marketplace
<!-- /generated:cli-reference -->

## Notes

**`check` is the CI gate.** `narro check deck.md --strict` promotes warnings to
errors and exits non-zero, which is the step a pipeline runs — the scaffolded
markdown templates map their `lint` script to exactly that. Plain `check` exits 0
on warnings, which makes it the right form for the edit loop and the wrong form
for CI.

Three flags, three different questions:

| Flag | Answers |
| --- | --- |
| `--render` | What does the slide render, and did that class land on the word or the paragraph? No browser. |
| `--strict` | Is anything at all wrong, including the warnings? Exit code for CI. |
| `--fit` | Does the content fit the canvas — and does the page render at all? The only check that opens a browser. **Not implied by `--strict`.** |
| `--fit-if-available` | The same, but a missing browser is a warning rather than a failure |

See [Verifying a deck](/docs/verifying.md) for what each of these sees and does not see.


**`narro build <deck>.md` measures fit for you.** A single-file deck has no
`package.json` to wire a check into, so the build runs one: it reports the
overflow and exits non-zero. A machine with no browser gets a warning rather
than a failure — `narro check dist --fit` is the strict form — and `--no-fit`
turns it off entirely. This is the only fit check a `narro new` deck gets,
because it is the only place there is to put one.

**`--fit` and React mode.** `check` is markdown-only, but `--fit` measures built
output: `npm run build && npx @getnarro/cli check dist --fit` works for a React
deck and is the only fit check either mode has. Every React template ships a
`fit` script that runs exactly that. It needs Chromium
(`npx playwright install chromium`); **without one it fails**, because a check
that measured nothing is not a check that passed. `--fit-if-available` makes that
a warning when you want it to be one, and
`NARRO_CHROMIUM=/path/to/chromium` points it at a browser your image already has.

**Formatting.** Use `narro fmt`, not Prettier — a markdown formatter can reflow a
paragraph and move an attribute block onto its own line, which changes what it
styles with nothing to report it. See
[Formatting a deck](/docs/markdown-mode.md#formatting-a-deck).

**Scaffolding.** `npm create narro@latest my-deck` and `narro create my-deck`
run the same code. `narro new deck.md` is different: it writes a single markdown
file with no project around it.

**Markdown mode.** Passing a `.md` file to `dev` or `build` switches to markdown
mode, where no project or config file is needed — the CLI brings its own
runtime.

**Export fidelity.** A static build keeps animations, embeds, and live
components working. PPTX maps slides onto real PowerPoint shapes so text stays
editable, but anything driven by a live component becomes its rendered state.
PDF flattens fragments to their final state.

**Credentials.** Google Slides import and export need Google OAuth credentials
in the environment. `create-template-from-screenshots` and
`analyze-slides-for-components` call a hosted vision model and need
`ANTHROPIC_API_KEY` or `OPENAI_API_KEY`.