CLI reference¶

All commands are available through the inkflow entry point. Run inkflow --help for the top-level list, or inkflow COMMAND --help for any single command.

inkflow¶

Beautiful slides from SVG. Your editor, your style.

Usage:

inkflow [OPTIONS] COMMAND [ARGS]...

Options:

  --version                       Show the version and exit.
  --log-level [off|debug|info|warning|error]
                                  Baseline level for every sink (console,
                                  file, browser).
  --log-level-console [off|debug|info|warning|error]
                                  Console/TUI level [default: warning].
                                  Overrides --log-level.
  --log-level-file [off|debug|info|warning|error]
                                  File level [default: off]. Overrides --log-
                                  level.
  --log-level-browser [off|debug|info|warning|error]
                                  Presenter banner level [default: warning].
                                  Overrides --log-level.
  --log-file PATH                 File-sink destination (default: per-user log
                                  dir). Does not enable the sink.
  --help                          Show this message and exit.

inkflow add¶

Create a new slide SVG, optionally wired to a layout parent.

OUTPUT is the path for the new SVG file. With -p/--parent, the slide is wired to that layout (bare name, 'local:foo', 'theme:foo', 'builtin:foo', or a relative path) and given preview layers. Without it, a blank slide is created.

Usage:

inkflow add [OPTIONS] OUTPUT

Options:

  -p, --parent TEXT  Layout name or inkflow:parent string; omit for a blank
                     slide.
  -d, --deck PATH    Path to deck.py (default: deck.py in cwd)
  --no-deck          Operate without a deck.py (for theme authoring). Only
                     builtin: and relative-path parents are allowed.
  --help             Show this message and exit.

inkflow build¶

Export a self-contained presentation directory for offline use.

Produces an index.html with every slide inlined and copies any assets the deck references into the output directory. No server is required to view it. Defaults to a build/ directory next to deck.py.

Usage:

inkflow build [OPTIONS]

Options:

  -d, --deck PATH    Path to deck.py (default: deck.py in cwd)
  -o, --output TEXT  Output directory (default: build/ next to deck.py)
  --help             Show this message and exit.

inkflow clean¶

Strip Inkscape editor metadata from SVG files.

If FILES is omitted, cleans every project-local SVG the deck uses (each slide and its local layout ancestors).

Usage:

inkflow clean [OPTIONS] [FILES]...

Options:

  -d, --deck PATH  Path to deck.py (default: deck.py in cwd)
  --stdout         Write to stdout instead of modifying files in place
  --check          Exit non-zero if any file would be modified, without
                   writing changes
  --help           Show this message and exit.

inkflow colorize¶

Replace hardcoded theme hex colors in SVG files with semantic CSS classes.

Reads the active theme's color tokens and replaces matching fill/stroke attributes and inline style declarations with inkflow-fill- / inkflow-stroke- classes. The hardcoded attributes are removed after replacement.

If FILES is omitted, colorizes every project-local SVG the deck uses (each slide and its local layout ancestors).

Usage:

inkflow colorize [OPTIONS] [FILES]...

Options:

  -d, --deck PATH      Path to deck.py (default: deck.py in cwd)
  --no-deck            Operate without a deck.py (for theme authoring). Only
                       builtin: and relative-path parents are allowed.
  --mode [dark|light]  Color mode for preview style (default: deck mode; dark
                       with --no-deck).
  --help               Show this message and exit.

inkflow completion¶

Print shell completion script for SHELL.

Add to your shell config:

bash: eval "$(inkflow completion bash)"
zsh: eval "$(inkflow completion zsh)"
fish: inkflow completion fish | source
carapace: inkflow completion carapace > ~/.config/carapace/specs/inkflow.yaml

Usage:

inkflow completion [OPTIONS] {bash|zsh|fish|carapace}

Options:

  --help  Show this message and exit.

inkflow export¶

Export a PDF via headless Chromium — one page per slide, no animations.

Requires a Chromium-based browser on the system; point --chromium at it if it is not auto-detected. Pass --no-sandbox when running as root or in Docker. Defaults to <deck-stem>.pdf next to deck.py.

Usage:

inkflow export [OPTIONS]

Options:

  -d, --deck PATH    Path to deck.py (default: deck.py in cwd)
  -o, --output TEXT  Output PDF path (default: <deck-stem>.pdf next to
                     deck.py)
  --chromium TEXT    Path to chromium/chrome binary (auto-detected if not set)
  --no-sandbox       Pass --no-sandbox to Chromium (needed when running as
                     root or in Docker).
  --size WxH         Override PDF page size, e.g. 1280x720. Auto-detected from
                     slides if not set.
  --help             Show this message and exit.

inkflow init¶

Scaffold a new presentation project in DIRECTORY (default: current).

Writes a starter deck.py, a title SVG, and a Markdown content slide. When run inside a git repository it also configures the SVG git hooks (skip with --no-git). Pass --theme to start from a custom theme directory.

Usage:

inkflow init [OPTIONS] [DIRECTORY]

Options:

  --theme TEXT  Path to a custom theme directory.
  --no-git      Skip git hook setup even when inside a git repository.
  --help        Show this message and exit.

inkflow layouts¶

List available layouts with their zones and parent chain.

Discovers layouts from three sources — built-in, theme, then project-local — and prints a table per source with each layout's parent chain and zone names. The default zone is underlined; a checkmark marks layouts that carry a slide number (a zone-slide-number or zone-slide-total). Pass --no-deck to list only the built-in layouts.

Usage:

inkflow layouts [OPTIONS]

Options:

  -d, --deck PATH  Path to deck.py (default: deck.py in cwd)
  --no-deck        Operate without a deck.py (for theme authoring). Only
                   builtin: and relative-path parents are allowed.
  --help           Show this message and exit.

inkflow palette¶

Generate an Inkscape GPL color palette for the active theme.

Writes a .gpl palette to stdout whose colors correspond to the inkflow-fill- / inkflow-stroke- CSS class tokens so you can pick theme colors by name in Inkscape's swatches panel and then run 'inkflow colorize' to convert the hardcoded hex values to semantic classes. Redirect it to save:

inkflow palette > inkflow.gpl

Usage:

inkflow palette [OPTIONS]

Options:

  -d, --deck PATH      Path to deck.py (default: deck.py in cwd)
  --no-deck            Operate without a deck.py (for theme authoring). Only
                       builtin: and relative-path parents are allowed.
  --mode [dark|light]  Color mode for preview style (default: deck mode; dark
                       with --no-deck).
  --help               Show this message and exit.

inkflow parent¶

Manage slide layout parents.

Usage:

inkflow parent [OPTIONS] COMMAND [ARGS]...

Options:

  --help  Show this message and exit.

inkflow parent get¶

Print the inkflow:parent value of slide SVGs.

With FILES, prints each file's parent (a bare value for a single file, else one 'file: parent' line each). With FILES omitted, lists every slide in the deck alongside its parent.

Usage:

inkflow parent get [OPTIONS] [FILES]...

Options:

  -d, --deck PATH  Path to deck.py (default: deck.py in cwd)
  --help           Show this message and exit.

inkflow parent set¶

Set the inkflow:parent of a slide SVG and refresh its layout layers.

PARENT is a layout name or inkflow:parent string: bare name (three-level search), 'local:foo', 'theme:foo', 'builtin:foo', or a relative path.

Usage:

inkflow parent set [OPTIONS] FILE PARENT

Options:

  -d, --deck PATH  Path to deck.py (default: deck.py in cwd)
  --no-deck        Operate without a deck.py (for theme authoring). Only
                   builtin: and relative-path parents are allowed.
  --help           Show this message and exit.

inkflow parent strip¶

Remove inkflow:parent and injected layout layers from slide SVG(s).

If FILES is omitted, strips every project-local SVG the deck uses (each slide and its local layout ancestors).

Usage:

inkflow parent strip [OPTIONS] [FILES]...

Options:

  -y, --yes        Skip confirmation prompt.
  -d, --deck PATH  Path to deck.py (default: deck.py in cwd)
  --help           Show this message and exit.

inkflow serve¶

Start the presentation server with live reload.

Serves the deck at http://{host}:{port} and pushes slide updates over a WebSocket whenever a source file changes, swapping content in place without a full page reload. Use --host 0.0.0.0 to expose the server on all interfaces.

Keyboard shortcuts in the terminal:

o: open the presentation in a browser
r: force a rebuild
t: toggle the error trace
q: quit (Ctrl-D and Ctrl-C also work)

Usage:

inkflow serve [OPTIONS]

Options:

  -d, --deck PATH    Path to deck.py (default: deck.py in cwd)
  --host TEXT        Bind address  [default: localhost]
  --port INTEGER     HTTP port  [default: 7777]
  --ws-port INTEGER  WebSocket port  [default: 7778]
  --help             Show this message and exit.

inkflow setup-git¶

Configure git hooks and the SVG diff driver for the current repository.

Run once per clone. Installs a pre-commit hook that strips Inkscape editor metadata from staged SVGs, and registers a diff driver so git diff and GitHub show only visual changes for SVGs. Both git-config entries are local to the clone (never committed).

Usage:

inkflow setup-git [OPTIONS]

Options:

  --help  Show this message and exit.

inkflow sync¶

Refresh layout layers and preview styles in slide SVG(s).

Injects ancestor layout layers for editor preview and a style block so Inkscape renders semantic CSS classes (e.g. inkflow-fill-accent) with the correct theme colors.

If FILES is omitted, refreshes every project-local SVG the deck uses (each slide and its local layout ancestors). Use --no-deck when authoring a theme without a project deck.py.

Usage:

inkflow sync [OPTIONS] [FILES]...

Options:

  --check              Report stale files without rewriting. Exits 1 if any
                       are stale.
  -d, --deck PATH      Path to deck.py (default: deck.py in cwd)
  --no-deck            Operate without a deck.py (for theme authoring). Only
                       builtin: and relative-path parents are allowed.
  --mode [dark|light]  Color mode for preview style (default: deck mode; dark
                       with --no-deck).
  --help               Show this message and exit.

inkflow verify¶

Check slides for authoring errors before presenting or building.

Runs per-slide checks and prints an ok / error / warn line for each. Errors: the SVG source, .md, notes file, or Media.src is missing; a zone id (from zones keys or ::zone:: markers) or an animation element id is absent from the composed SVG. Warnings: animation steps are not contiguous from 1, or layout layers are stale (run inkflow sync).

Exits 1 on any error, or on any warning when --strict is set. Hidden slides (visible=False) are skipped unless --all is passed.

Usage:

inkflow verify [OPTIONS] [FILES]...

Options:

  -d, --deck PATH  Path to deck.py (default: deck.py in cwd)
  --all            Include hidden slides.
  --strict         Treat warnings as errors (exit 1 if any warn).
  --help           Show this message and exit.

Output and diagnostics¶

Status lines, warnings, and errors print to stderr; machine-readable output (the palette and completion scripts, parent get values, and clean --stdout) stays on stdout so it can be redirected cleanly.

Diagnostics flow through three independent sinks, each with its own level (off, debug, info, warning, error — off disables the sink):

console — stderr for every command, or the live serve TUI in its place. Default warning.
file — an optional on-disk log, off by default. When enabled without an explicit path it writes to the per-user log directory (~/.local/state/inkflow/log/ on Linux, ~/Library/Logs/inkflow/ on macOS, %LOCALAPPDATA%\inkflow\Logs\ on Windows).
browser — the presenter's message banner during serve. Default warning.

Set a baseline for every sink with --log-level, or target one sink; a per-sink setting overrides the baseline. Each flag has an environment-variable twin, and a per-sink setting (flag or env) beats the --log-level baseline:

Scope	Flag	Environment variable
all sinks	`--log-level LEVEL`	`INKFLOW_LOG_LEVEL`
console / TUI	`--log-level-console LEVEL`	`INKFLOW_LOG_LEVEL_CONSOLE`
file	`--log-level-file LEVEL`	`INKFLOW_LOG_LEVEL_FILE`
browser	`--log-level-browser LEVEL`	`INKFLOW_LOG_LEVEL_BROWSER`
file destination	`--log-file PATH`	`INKFLOW_LOG_FILE`

--log-file only sets where the file sink writes; it does not enable it — raise the file level above off for that. These are global options, so they come before the subcommand (the environment twins are position-independent):

inkflow --log-level-file debug build              # archive a full trace to the default path
inkflow --log-level-console off serve             # silence the TUI log list; banner unaffected
inkflow --log-level debug --log-file run.log build  # every sink at debug, file to ./run.log
INKFLOW_LOG_LEVEL_FILE=debug inkflow build        # same as the first, via the environment

A fatal build error is shown as a full-screen overlay (and the serve TUI error view), separate from these sinks; enabling the file sink also captures its traceback.