CLI

Which command do I run, and what are its flags?

16 min readView as markdown10 chunks · 5.1k tokens in docspack

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

Command	What it does
`narro analyze-slides-for-components`	Analyze presentation slides to identify needed shared-ui components
`narro annotate <file>`	Bake a notes track into a recording — captions, callouts and spotlights
`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 cast <file>`	Read a recording back — its shape, its length, and the chapters it carries
`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 notes <file>`	Draft a narration track from a transcript, resolving what it points at
`narro preview`	Preview built presentation
`narro record <url>`	Record a web app into an embeddable cast — real DOM, not video
`narro review <file>`	Review a recording — dead clicks, dead air, unreadable type, leaked input
`narro themes`	Browse and apply themes from the marketplace

Reference

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

`narro analyze-slides-for-components`

Analyze presentation slides to identify needed shared-ui components

narro analyze-slides-for-components [options]

Effects

readwritenetwork

effects: read, write, network

Options

-d, --screenshots-dir <dir>
Directory containing screenshot files
-s, --screenshots <paths>...repeatable
Screenshot file paths
-o, --output <file>default ./component-analysis.md
Output markdown file
-p, --provider <provider>one of openai, claude; default openai
AI provider (openai or claude)
-m, --model <model>
AI model to use

Inherited options

-V, --version
output the version number
--cmdspec
print this program's cmdspec document as JSON, and exit
-h, --help
display help for command

Exit statuses

0success
1the command failed, or was used wrongly

Examples

$ narro analyze-slides-for-components --screenshots-dir shots

Build a command line

narro analyze-slides-for-components

`narro annotate`

Bake a notes track into a recording — captions, callouts and spotlights

narro annotate <file> [options]

Effects

readwrite

effects: read, write

Arguments

<file>required
the .narrocast to annotate

Options

-n, --notes <path>
the track to bake in, a .notes.md
-o, --out <path>
write here instead of over the recording
--clear
remove the track the recording is carrying
--uieffects become: read, write, network; then runs until stopped
open the editor, over the track the recording already has
--port <number>integer; 1 to 65535; default 4477
the port the editor listens on

Inherited options

-V, --version
output the version number
--cmdspec
print this program's cmdspec document as JSON, and exit
-h, --help
display help for command

Exit statuses

0success
1the command failed, or was used wrongly

Examples

$ narro annotate demo.narrocast --notes demo.notes.md

Edit the track in a browser

$ narro annotate demo.narrocast --ui

Build a command line

narro annotate <file>

`narro build`

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

With a .md file, builds that deck to a static site and then measures every slide for overflow in a headless browser, failing when one overflows. Without one, builds the React project in the working directory.

narro build [<file>] [options]

Effects

readwriteexec

effects: read, write, exec; idempotent

Arguments

[<file>]
path to a markdown deck to build directly

Options

-o, --outDir <dir>default dist
output directory
--base <path>
base path for deployment
--no-fiteffects become: read, write
skip the overflow measurement after building

Inherited options

-V, --version
output the version number
--cmdspec
print this program's cmdspec document as JSON, and exit
-h, --help
display help for command

Exit statuses

0success
1the build failed, or a slide overflows (markdown mode)

Examples

$ narro build deck.md

$ narro build deck.md --outDir site --base /talks/q3/

Build a command line

narro build

`narro bundle`

Bundle presentation into a single self-contained HTML file

narro bundle [options]

Effects

readwriteexec

effects: read, write, exec

Options

-o, --output <filename>default presentation.html
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)

Inherited options

-V, --version
output the version number
--cmdspec
print this program's cmdspec document as JSON, and exit
-h, --help
display help for command

Exit statuses

0success
1the command failed, or was used wrongly

Examples

$ narro bundle --output talk.html --inline-assets

Build a command line

narro bundle

`narro capture-website`

Capture a full-page screenshot of a website

narro capture-website <url> [options]

Effects

writenetworkexec

effects: write, network, exec

Arguments

<url>required
URL of the website to capture

Options

-o, --output <path>
Output file path (default: screenshot.png)
-f, --full-page
Capture full page (scrollable content)
-w, --width <number>integer; at least 1; default 1920
Viewport width in pixels
-h, --height <number>integer; at least 1; default 1080
Viewport height in pixels
-d, --delay <number>integer; at least 0; default 2000
Delay before screenshot in milliseconds
--help
display help for command

Inherited options

-V, --version
output the version number
--cmdspec
print this program's cmdspec document as JSON, and exit

Exit statuses

0success
1the command failed, or was used wrongly

Examples

$ narro capture-website https://example.com --output site.png

Build a command line

narro capture-website <url>

`narro cast`

Read a recording back — its shape, its length, and the chapters it carries

narro cast <file> [options]

Effects

read

effects: read; idempotent

Arguments

<file>required
the .narrocast to read

Options

--json
print the summary as JSON

Inherited options

-V, --version
output the version number
--cmdspec
print this program's cmdspec document as JSON, and exit
-h, --help
display help for command

Input and output

stdout
text/plain, the recording's shape, length and chapters
application/json, the same summary with --json

Exit statuses

0success
1the command failed, or was used wrongly

Examples

$ narro cast demo.narrocast --json

Build a command line

narro cast <file>

`narro check`

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

The fast loop. Resolves every layout, slot, theme, component and frontmatter name in a markdown deck, and names the ones that do not exist along with what would have worked. Given a built directory and --fit, measures it instead — the only check React mode has.

narro check <file|dir> [options]

Effects

read

effects: read; idempotent

Arguments

<file|dir>required
path to the deck file (e.g. deck.md), or a built dist/ directory

Options

--strict
treat warnings as errors
--render
print what each slide renders — elements, classes, and text
--fiteffects become: read, exec
render the deck in a headless browser and report slides whose content overflows
--fit-if-availableeffects become: read, exec
like --fit, but only warn when no browser is installed
--render-full
like --render, but print long text and large props in full

Inherited options

-V, --version
output the version number
--cmdspec
print this program's cmdspec document as JSON, and exit
-h, --help
display help for command

Input and output

stdout
text/plain, the problems found, each with a fix

Exit statuses

0success
1the deck has errors, warnings under --strict, or slides that overflow under --fit

Examples

$ narro check deck.md

What CI should run

$ narro check deck.md --strict --fit

See what each slide renders, no browser

$ narro check deck.md --render

Measure a built React project

$ narro check dist --fit

Build a command line

narro check <file|dir>

`narro comments`

Manage slide comments

narro comments <command> [options]

Inherited options

-V, --version
output the version number
--cmdspec
print this program's cmdspec document as JSON, and exit
-h, --help
display help for command

Commands

narro comments list
List all comments in the presentation
narro comments add
Add a new comment to a slide
narro comments export
Export comments to a file
narro comments import
Import comments from a file
narro comments help
display help for command

Exit statuses

0success
1the command failed, or was used wrongly

`narro comments list`

List all comments in the presentation

narro comments list [options]

Effects

read

effects: read; idempotent

Options

-s, --slide-id <id>
filter by slide ID
-a, --author <name>
filter by author name
-r, --resolved <status>one of true, false, all; default all
filter by resolved status (true, false, all)
-f, --format <format>one of table, json; default table
output format (table, json)

Inherited options

-V, --version
output the version number
--cmdspec
print this program's cmdspec document as JSON, and exit
-h, --help
display help for command

Input and output

stdout
text/plain, a table of comments
application/json, the comments with --format=json

Exit statuses

0success
1the command failed, or was used wrongly

Examples

$ narro comments list --resolved false --format json

Build a command line

narro comments list

`narro comments add`

Add a new comment to a slide

narro comments add [options]

Effects

write

effects: write

Options

-s, --slide-id <id>required
slide ID to add comment to
-a, --author <name>required
comment author name
-c, --content <text>required
comment content
-x, --position-x <number>
inline comment X position (0-100)
-y, --position-y <number>
inline comment Y position (0-100)

Inherited options

-V, --version
output the version number
--cmdspec
print this program's cmdspec document as JSON, and exit
-h, --help
display help for command

Exit statuses

0success
1the command failed, or was used wrongly

Examples

$ narro comments add --slide-id intro --author Sam --content "Tighten this"

Build a command line

narro comments add --slide-id <id> --author <name> --content <text>

`narro comments export`

Export comments to a file

narro comments export [options]

Effects

readwrite

effects: read, write

Options

-o, --output <file>
output file path
-f, --format <format>one of markdown, html, json; default markdown
export format (markdown, html, json)
--include-resolved
include resolved comments

Inherited options

-V, --version
output the version number
--cmdspec
print this program's cmdspec document as JSON, and exit
-h, --help
display help for command

Exit statuses

0success
1the command failed, or was used wrongly

Examples

$ narro comments export --format markdown --output review.md

Build a command line

narro comments export

`narro comments import`

Import comments from a file

narro comments import [options]

Effects

write

effects: write

Options

-i, --input <file>required
input JSON file path
-m, --mergeeffects become: write
merge with existing comments instead of replacing

Inherited options

-V, --version
output the version number
--cmdspec
print this program's cmdspec document as JSON, and exit
-h, --help
display help for command

Exit statuses

0success
1the command failed, or was used wrongly

Examples

$ narro comments import --input review.json --merge

Build a command line

narro comments import --input <file>

`narro comments help`

display help for command

narro comments help [<command>] [options]

Effects

effects: none

Arguments

[<command>]

Inherited options

-V, --version
output the version number
--cmdspec
print this program's cmdspec document as JSON, and exit
-h, --help
display help for command

Exit statuses

0success
1the command failed, or was used wrongly

Examples

$ narro comments help add

Build a command line

narro comments help

`narro create`

Create a new Narro presentation project

narro create [<project-name>] [options]

Effects

writenetworkexec

effects: write, network, exec; prompts on a terminal unless --yes

Arguments

[<project-name>]
Name of the project to create

Options

-V, --version
output the version number
-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-installeffects become: write
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
--listeffects become: none
List every template with what it is, and exit

Inherited options

--cmdspec
print this program's cmdspec document as JSON, and exit
-h, --help
display help for command

Exit statuses

0success
1the command failed, or was used wrongly

Examples

$ narro create my-talk --template markdown-minimal --yes

Every template, with what it is

$ narro create --list

Build a command line

narro create

`narro create-template-from-screenshots`

Generate a template from presentation screenshots using AI

narro create-template-from-screenshots [<template-name>] [options]

Effects

readwritenetwork

effects: read, write, network

Arguments

[<template-name>]
Name of the template to create

Options

-s, --screenshots <paths>...repeatable
Screenshot file paths
-o, --output <dir>default ./templates
Output directory
-p, --provider <provider>one of openai, claude; default openai
AI provider (openai or claude)
-m, --model <model>
AI model to use

Inherited options

-V, --version
output the version number
--cmdspec
print this program's cmdspec document as JSON, and exit
-h, --help
display help for command

Exit statuses

0success
1the command failed, or was used wrongly

Examples

$ narro create-template-from-screenshots acme --screenshots a.png b.png --provider claude

Build a command line

narro create-template-from-screenshots

`narro dev`

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

narro dev [<file>] [options]

Effects

readnetwork

effects: read, network; runs until stopped

Arguments

[<file>]
path to a markdown deck to serve directly

Options

-p, --port <number>integer; 1 to 65535; default 3000
port to use
--host
expose to network
-o, --openundone by --no-open
open browser on startup
--theme <name>
theme override (markdown mode)

Inherited options

-V, --version
output the version number
--cmdspec
print this program's cmdspec document as JSON, and exit
-h, --help
display help for command

Exit statuses

0success
1the command failed, or was used wrongly

Examples

Serve one markdown deck with live reload

$ narro dev deck.md

Serve a React project

$ narro dev --port 3001

Build a command line

narro dev

`narro export`

Export presentation to static files, PPTX, or Google Slides

PDF and PNG render in a headless browser and need Playwright. `--to google-slides` uploads to Google Drive and needs OAuth credentials; every other format stays on this machine.

narro export [<file>] [options]

Effects

readwriteexecnetwork

effects: read, write, exec, network

Arguments

[<file>]
path to a markdown deck to export directly

Options

-o, --outDir <dir>default dist
output directory for HTML export
--pdf
export to PDF (requires Playwright)
--png
export slides as PNG images (requires Playwright)
--to <format>one of pptx, google-slides
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>integer; at least 0
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>env GOOGLE_CLIENT_ID
Google OAuth client ID
--google-client-secret <secret>env GOOGLE_CLIENT_SECRET; secret, so prefer the environment variable
Google OAuth client secret
--google-refresh-token <token>env GOOGLE_REFRESH_TOKEN; secret, so prefer the environment variable
Google OAuth refresh token

Inherited options

-V, --version
output the version number
--cmdspec
print this program's cmdspec document as JSON, and exit
-h, --help
display help for command

Exit statuses

0success
1the command failed, or was used wrongly

Examples

$ narro export deck.md --pdf

$ narro export deck.md --png --outDir slides

$ narro export --to pptx --output-path talk.pptx

Build a command line

[<file>]

--outDir

output directory for HTML export

--pdf — export to PDF (requires Playwright)--png — export slides as PNG images (requires Playwright)

--to

export format: pptx, google-slides

--output-path

output file path for PPTX export

--include-notes — include speaker notes in export--include-animations — include animations in export

--settle

milliseconds to let a slide's animations finish before capturing (default: 4000)

--input-path

path to presentation project

--template-path

PowerPoint template file (.potx or .pptx) to apply

--template-id

Google Slides template presentation ID to copy from

--google-client-id

Google OAuth client ID

--google-client-secret

Google OAuth client secret

--google-refresh-token

Google OAuth refresh token

Inherited options

--version — output the version number--cmdspec — print this program's cmdspec document as JSON, and exit--help — display help for command

narro export

`narro fmt`

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

narro fmt <file> [options]

Effects

readwrite

effects: read, write; idempotent

Arguments

<file>required
path to the deck file (e.g. deck.md)

Options

--checkeffects become: read
report whether the deck is formatted, and exit non-zero if not

Inherited options

-V, --version
output the version number
--cmdspec
print this program's cmdspec document as JSON, and exit
-h, --help
display help for command

Exit statuses

0success
1the deck could not be read, or is not formatted under --check

Examples

$ narro fmt deck.md

$ narro fmt deck.md --check

Build a command line

narro fmt <file>

`narro import`

Import presentation from PowerPoint or Google Slides

narro import <source> [options]

Effects

readwritenetwork

effects: read, write, network

Arguments

<source>required
source file path or Google Slides presentation ID/URL

Options

--from <source>requiredone of pptx, google-slides
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>env GOOGLE_CLIENT_ID
Google OAuth client ID
--google-client-secret <secret>env GOOGLE_CLIENT_SECRET; secret, so prefer the environment variable
Google OAuth client secret
--google-refresh-token <token>env GOOGLE_REFRESH_TOKEN; secret, so prefer the environment variable
Google OAuth refresh token

Inherited options

-V, --version
output the version number
--cmdspec
print this program's cmdspec document as JSON, and exit
-h, --help
display help for command

Exit statuses

0success
1the command failed, or was used wrongly

Examples

$ narro import talk.pptx --from pptx --output-dir talk

Build a command line

narro import --from <source> <source>

`narro new`

Scaffold a starter markdown deck

narro new <file> [options]

Effects

write

effects: write

Arguments

<file>required
path to the new deck file (e.g. deck.md)

Inherited options

-V, --version
output the version number
--cmdspec
print this program's cmdspec document as JSON, and exit
-h, --help
display help for command

Exit statuses

0success
1the command failed, or was used wrongly

Examples

$ narro new deck.md

Build a command line

narro new <file>

`narro notes`

Draft a narration track from a transcript, resolving what it points at

narro notes <file> [options]

Effects

readwrite

effects: read, write

Arguments

<file>required
the .narrocast the transcript narrates

Options

-f, --from <path>
the transcript: WebVTT, SRT, or Whisper's JSON
-o, --out <path>
where to write the draft (default: beside the recording)
--offset <ms>integer
shift the transcript, when it and the recording started apart
--raw
keep the transcript's own cue lengths instead of joining sentences

Inherited options

-V, --version
output the version number
--cmdspec
print this program's cmdspec document as JSON, and exit
-h, --help
display help for command

Exit statuses

0success
1the command failed, or was used wrongly

Examples

$ narro notes demo.narrocast --from narration.vtt

Build a command line

narro notes <file>

`narro preview`

Preview built presentation

narro preview [options]

Effects

readnetwork

effects: read, network; runs until stopped

Options

-p, --port <number>integer; 1 to 65535; default 4173
port to use
--host
expose to network
-o, --open
open browser on startup
-d, --outDir <dir>
serve a directory of built output directly

Inherited options

-V, --version
output the version number
--cmdspec
print this program's cmdspec document as JSON, and exit
-h, --help
display help for command

Exit statuses

0success
1the command failed, or was used wrongly

Examples

$ narro preview --outDir dist

Build a command line

narro preview

`narro record`

Record a web app into an embeddable cast — real DOM, not video

narro record <url> [options]

Effects

writenetworkexec

effects: write, network, exec

Arguments

<url>required
the page to record

Options

-o, --out <path>default recording.narrocast
where to write the cast
--size <WxH>default 1440x900
recording viewport — the window is sized to match
--connect[=<endpoint>]
record a Chrome you already have open, signed in, with your extensions — start it with --remote-debugging-port and a --user-data-dir of its own
--auto <seconds>number; at least 0
record headless, scrolling the page, instead of opening a window
--mask
mask input values and drop scripts and comments
--chapters <path>
a JSON file of named marks — [{ "name": "publish", "atMs": 4200 }] — for the recordings no one is sitting through
--mic[=<path>]
also capture the operator's narration, for a transcript to draft a track from (needs ffmpeg)
--transcribe[=<binary>]
run a Whisper-shaped binary over what --mic caught (default: whisper-cli)
--notes <path>
a .notes.md track to bake in — captions, callouts and spotlights over the recording
--html <path>
also write a standalone page that plays it
--embed <dir>
also write the player, the cast and a snippet for a website
--poster <path>
also write a PNG of the last frame, for PDF and PPTX export
--cursor <mode>one of pointer, trail, none; default pointer
pointer, trail or none
--no-optimize
keep images exactly as the page served them
--prompt
print the prompt for a coding agent without asking first

Inherited options

-V, --version
output the version number
--cmdspec
print this program's cmdspec document as JSON, and exit
-h, --help
display help for command

Exit statuses

0success
1the command failed, or was used wrongly

Examples

Opens a window to drive

$ narro record https://localhost:5173 --out demo.narrocast

Headless, no window

$ narro record https://example.com --auto 8 --mask

Build a command line

<url>Required

--out

where to write the cast

--size

recording viewport — the window is sized to match

--connect

record a Chrome you already have open, signed in, with your extensions — start it with --remote-debugging-port and a --user-data-dir of its own

--auto

record headless, scrolling the page, instead of opening a window

--mask — mask input values and drop scripts and comments

--chapters

a JSON file of named marks — [{ "name": "publish", "atMs": 4200 }] — for the recordings no one is sitting through

--mic

also capture the operator's narration, for a transcript to draft a track from (needs ffmpeg)

--transcribe

run a Whisper-shaped binary over what --mic caught (default: whisper-cli)

--notes

a .notes.md track to bake in — captions, callouts and spotlights over the recording

--html

also write a standalone page that plays it

--embed

also write the player, the cast and a snippet for a website

--poster

also write a PNG of the last frame, for PDF and PPTX export

--cursor

pointer, trail or none

--no-optimize — keep images exactly as the page served them--prompt — print the prompt for a coding agent without asking first

Inherited options

--version — output the version number--cmdspec — print this program's cmdspec document as JSON, and exit--help — display help for command

narro record <url>

`narro review`

Review a recording — dead clicks, dead air, unreadable type, leaked input

narro review <file> [options]

Effects

read

effects: read; idempotent

Arguments

<file>required
the .narrocast to review

Options

--rules <list>
a comma-separated subset (leaked-input, dead-click, dead-air, scroll-rush, illegible, unchaptered, chapter-gap)
--strict
fail on warnings too, not only on errors
--out <path>effects become: read, write
also write the briefing, for a person or a coding agent
--embed-width <px>integer; at least 1
the width the demo will be shown at, for legibility
--json
print the findings as JSON

Inherited options

-V, --version
output the version number
--cmdspec
print this program's cmdspec document as JSON, and exit
-h, --help
display help for command

Input and output

stdout
text/plain, the findings
application/json, the findings with --json

Exit statuses

0success
1the recording has errors, or warnings under --strict

Examples

$ narro review demo.narrocast --strict

Build a command line

narro review <file>

`narro themes`

Browse and apply themes from the marketplace

narro themes <command> [options]

Inherited options

-V, --version
output the version number
--cmdspec
print this program's cmdspec document as JSON, and exit
-h, --help
display help for command

Commands

narro themes list
List all available themes or color schemes
narro themes info
Get detailed information about a theme or color scheme
narro themes apply
Apply a theme or color scheme to the current project
narro themes help
display help for command

Exit statuses

0success
1the command failed, or was used wrongly

`narro themes list`

List all available themes or color schemes

narro themes list [options]

Effects

read

effects: read; idempotent

Options

-t, --tags <tags>
filter by tags (comma-separated)
-q, --query <query>
search by name or description
-c, --color-schemes
list color schemes instead of themes

Inherited options

-V, --version
output the version number
--cmdspec
print this program's cmdspec document as JSON, and exit
-h, --help
display help for command

Exit statuses

0success
1the command failed, or was used wrongly

Examples

$ narro themes list

$ narro themes list --color-schemes

Build a command line

narro themes list

`narro themes info`

Get detailed information about a theme or color scheme

narro themes info <id> [options]

Effects

read

effects: read; idempotent

Arguments

<id>required

Inherited options

-V, --version
output the version number
--cmdspec
print this program's cmdspec document as JSON, and exit
-h, --help
display help for command

Exit statuses

0success
1the command failed, or was used wrongly

Examples

$ narro themes info ocean

Build a command line

narro themes info <id>

`narro themes apply`

Apply a theme or color scheme to the current project

narro themes apply <id> [options]

Effects

write

effects: write; idempotent

Arguments

<id>required

Options

-c, --color-scheme
apply as a color scheme (colors only)

Inherited options

-V, --version
output the version number
--cmdspec
print this program's cmdspec document as JSON, and exit
-h, --help
display help for command

Exit statuses

0success
1the command failed, or was used wrongly

Examples

$ narro themes apply ocean

Build a command line

narro themes apply <id>

`narro themes help`

display help for command

narro themes help [<command>] [options]

Effects

effects: none

Arguments

[<command>]

Inherited options

-V, --version
output the version number
--cmdspec
print this program's cmdspec document as JSON, and exit
-h, --help
display help for command

Exit statuses

0success
1the command failed, or was used wrongly

Examples

$ narro themes help list

Build a command line

narro themes help

`narro help`

display help for command

narro help [<command>] [options]

Effects

effects: none; idempotent

Arguments

[<command>]

Inherited options

-V, --version
output the version number
--cmdspec
print this program's cmdspec document as JSON, and exit
-h, --help
display help for command

Exit statuses

0success
1the command failed, or was used wrongly

Examples

$ narro help check

Build a command line

narro help

The CLI as data

Everything on this page also exists as one machine-readable document, in cmdspec — what OpenAPI is for an HTTP API, for a command line. It carries what --help does, and what --help leaves out: the type and default of every value, what running a command changes, what it prints, and what its exit status means. A tool or an agent reading it can tell that narro check only reads the deck and narro fmt rewrites it, without running either.

Three ways to get it, all the same document for the version you have:

npx @getnarro/cli --cmdspec > narro.cmdspec.json     # the installed CLI prints it
cat node_modules/@getnarro/cli/dist/cmdspec.json      # it ships in the package
curl -s https://getnarro.com/cmdspec.json             # the latest release

@getnarro/cli names the file in its package.json ("cmdspec": "./dist/cmdspec.json"), which is how tools find it without being told. It is also importable as @getnarro/cli/cmdspec.json.

What each command changes

Every command states its effects, in cmdspec’s five words: read (files or state beyond its arguments), write (creates or changes local files), destructive (removes something), network (talks to another machine) and exec (runs another program, such as a headless browser). “none” means the command changes nothing; an option that changes the answer — fmt --check reads instead of writing — says so in the document.

Command	Effects	Also
`narro analyze-slides-for-components`	`read`, `write`, `network`	—
`narro annotate`	`read`, `write`	—
`narro build`	`read`, `write`, `exec`	idempotent
`narro bundle`	`read`, `write`, `exec`	—
`narro capture-website`	`write`, `network`, `exec`	—
`narro cast`	`read`	idempotent
`narro check`	`read`	idempotent
`narro comments list`	`read`	idempotent
`narro comments add`	`write`	—
`narro comments export`	`read`, `write`	—
`narro comments import`	`write`	—
`narro create`	`write`, `network`, `exec`	—
`narro create-template-from-screenshots`	`read`, `write`, `network`	—
`narro dev`	`read`, `network`	runs until stopped
`narro export`	`read`, `write`, `exec`, `network`	—
`narro fmt`	`read`, `write`	idempotent
`narro import`	`read`, `write`, `network`	—
`narro new`	`write`	—
`narro notes`	`read`, `write`	—
`narro preview`	`read`, `network`	runs until stopped
`narro record`	`write`, `network`, `exec`	—
`narro review`	`read`	idempotent
`narro themes list`	`read`	idempotent
`narro themes info`	`read`	idempotent
`narro themes apply`	`write`	idempotent

Asking about one command

docspack reads the document on its own. Any project that installs @getnarro/cli and runs npx docspack sync gets one entry per command, for exactly the installed version, and a question that names a command gets that command’s entry first:

npx docspack sync
npx docspack ask "narro export --pdf"

What comes back is the command’s digest — a help page, plus its effects, output and exit statuses:

narro fmt <file> [options]
  Normalise a deck's whitespace and frontmatter without changing what it renders
  <file>  path to the deck file (e.g. deck.md)
  --check  report whether the deck is formatted, and exit non-zero if not (effects become: read)
  also accepts: -V, --version, --cmdspec, -h, --help
  effects: read, write; idempotent
  exit: 0 success; 1 the deck could not be read, or is not formatted under --check
  $ narro fmt deck.md
  $ narro fmt deck.md --check

@getnarro/docspack carries the same entries beside the documentation, and npx @docspack/cmdspec digest narro.cmdspec.json fmt prints one without docspack at all.

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

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.