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.

--inline-assets embeds those assets in the HTML instead of copying them, so the whole deck is one file that cannot be separated from its images — worth it when the deck travels through a file picker, a chat window, or a sandboxed browser that only ever hands over the file you point at. The file grows by roughly a third of every asset, counted once per reference rather than once per file, and every byte of it loads before the first slide renders.

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)
  --inline-assets    Embed images and video as data URIs so the build is
                     index.html alone.
  --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, slides, and a pyproject.toml declaring inkflow. For a new project (not already inside a git repository) it also runs git init, writes a .gitignore, and configures the SVG git hooks. Inside an existing repository it leaves git alone and points you at setup-git. Skip all git steps with --no-git.

Refuses to scaffold into a non-empty directory (dotfiles like .git are ignored) unless --force is given.

Usage:

inkflow init [OPTIONS] [DIRECTORY]

Options:

  --no-git  Skip git hook setup even when inside a git repository.
  --force   Scaffold even into a non-empty directory.
  --help    Show this message and exit.

inkflow label2id

Promote each element's inkscape:label to its SVG id.

Name a group in Inkscape's Layers & Objects panel, run this, and deck.py can animate it by id (and the Morph transition can match it across slides). A label that is already a valid id is used verbatim; anything else is slugified. Labels need not be unique but ids must, so a clash is warned about and skipped, never clobbered. Elements inside injected inkflow preview layers are left alone.

If FILES is omitted, processes every project-local SVG the deck uses (each slide and its local layout/overlay ancestors). After renaming ids in a layout or overlay, run inkflow sync so the slides that preview it pick up the change.

Usage:

inkflow label2id [OPTIONS] [FILES]...

Options:

  -d, --deck PATH     Path to deck.py (default: deck.py in cwd)
  --all-tags          Also rename non-shape elements (tspan, stop, gradients,
                      …).
  --refs / --no-refs  Rewrite url(#id) / href='#id' references pointing at
                      renamed ids.
  -n, --dry-run       Show what would change without writing.
  --check             Exit non-zero if any file would change, without writing
                      (implies --dry-run).
  --help              Show this message and exit.

inkflow layouts

List available layouts and overlays with their zones and parent chain.

Discovers both from three sources — built-in, theme, then project-local — and prints a table per source with each entry's parent chain and zone names. The default zone is underlined; a checkmark marks entries that carry a slide number (a zone-slide-number or zone-slide-total). Layouts compose behind a slide, overlays on top of it, and the two are separate namespaces. The overlay section is omitted when no overlays exist. Pass --no-deck to list only the built-ins.

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, overlay layers and preview styles in slide SVG(s).

Injects ancestor layout layers below the slide and the overlays it gets at runtime above it, plus a style block so Inkscape renders semantic CSS classes (e.g. inkflow-fill-accent) with the correct theme colors.

Which overlays a file previews is decided by, in order: an explicit inkflow:preview-overlays attribute on the file, agreement among the slides backed by it, or the deck default. The rule that fired is shown per file. Overlay files themselves get no chrome, only an inkflow:preview backdrop.

If FILES is omitted, refreshes every project-local SVG the deck uses (each slide, its local layout ancestors, and the project's overlays). 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; an overlay paints an opaque full-canvas rect, which would hide the slide. Warnings: animation steps are not contiguous from 1, a zone id is declared twice after composition, 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.

Warnings raised by the libraries inkflow builds on are folded into the same sinks under the emitting library's name, at the level that library chose. They obey the flags below like any other record, instead of printing past them unformatted.

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.

Editing from the presenter

The presenter's Edit button (see Presenter panel) copies the current slide's source path to the clipboard by default. Set INKFLOW_EDIT_CMD to launch an editor instead, for every file kind, with {path} substituted (appended as a final argument if the template has no {path} placeholder). INKFLOW_EDIT_CMD_SVG overrides it specifically for SVG files, if you want a different command there (Inkscape instead of a text editor, say) without losing the general one for content, notes, and the deck script itself.

INKFLOW_EDIT_CMD="code -r --goto {path}" inkflow serve deck.py

Suggested editor commands

These are starting points to copy and adjust, not built-in behavior.

VS Code reuses an already-open window natively:

export INKFLOW_EDIT_CMD="code -r --goto {path}"

Neovim needs a fixed socket to connect to, since its own address is otherwise random per instance. Launch nvim with that socket, for example via a shell alias:

alias vim='nvim --listen /tmp/nvim.sock'

export INKFLOW_EDIT_CMD="nvim --server /tmp/nvim.sock --remote {path}"

If no nvim with that listen address is running, the command fails silently (logged as a warning server-side).

Inkscape has no comparable built-in remote-control flag, so this uses its D-Bus interface directly. Set it as INKFLOW_EDIT_CMD_SVG, not the general INKFLOW_EDIT_CMD. Save this as an executable script on your PATH:

#!/bin/sh
# Reuses a running Inkscape's window (a new tab on 1.5+, a new window on
# older versions) instead of spawning a second process; falls back to a
# plain `inkscape` launch if no instance is running yet.
if gdbus call --session --dest org.inkscape.Inkscape \
    --object-path /org/inkscape/Inkscape \
    --method org.freedesktop.Application.ActivateAction \
    "file-open-window" "[<'$1'>]" "{}" >/dev/null 2>&1; then
    exit 0
fi
exec inkscape "$1"

export INKFLOW_EDIT_CMD_SVG="inkflow-edit-svg {path}"

This is Linux-specific (D-Bus) and depends on Inkscape's own D-Bus interface, which isn't part of inkflow and could change between Inkscape releases. It degrades safely on any version, though.