CLICK-EXTRA-SCREENSHOT(1) CLICK-EXTRA-SCREENSHOT(1)

click-extra screenshot - Capture a command's colored output and write it as an image or HTML.

click-extra screenshot [OPTIONS] COMMAND_LINE...

Capture a command's colored output and write it as an image or HTML.

Runs COMMAND_LINE with colors forced on and its terminal width pinned, then writes the captured output where --output points. Its extension picks the format:

- .svg: a picture of a terminal window, for a surface that strips inline HTML. A README on GitHub or PyPI has no other option;

- .html: selectable, searchable, copy-pasteable text, for a page you own.

Put -- before the command line so its own options are not mistaken for this command's:

click-extra screenshot --output shot.svg -- my-cli --help

COMMAND_LINE is anything the shell can run, Click CLI or not. A Click CLI not built on Click Extra prints its help uncolored, so --wrap routes it through the wrap subcommand first and captures the colored rendering.

An SVG starts each run of text on its own column, so it renders correctly outside a web browser, where a file manager, a git client or a thumbnailer would otherwise slide the columns out of place.

Neither format needs an optional dependency.

--record runs the command under a pseudo-terminal instead, and writes an animated SVG of every screen it drew: the frames a spinner or a progress bar asks a terminal for, which a plain capture never sees. The invocation is drawn above every frame, and the loop pauses on the final screen for as long as its line count asks, see --hold.

Path of the file to write. Its extension picks the format: .svg for an image, .html for selectable text, .ansi for the escape sequences themselves. Pass - to print those to the terminal, which draws no window.
[required]
Terminal width, in characters, the command wraps its output to and the image is laid out at. Pass auto to pin neither: the command finds its own width, and the image is laid out at the longest line it printed, so nothing folds inside the picture.
Terminal chrome the capture is drawn on, and the palette its colors resolve against. Match it to the theme the captured CLI renders with: a light-background theme washes out on the dark default.
Terminal to draw the capture as: its window decorations, palette, font and prompt sigil. Anything stated alongside wins over it. Left out, the capture keeps the renderer's own neutral window.
Color of the frame drawn around the terminal window, as CSS names it. Pass none to draw no frame. Defaults to the one the chrome can show.
Thickness of that frame, in pixels.
How round the window's corners are, in pixels. Zero squares them. Defaults to 8, or to the rounding --preset terminal draws.
Color filling the image behind the window, margin included, as CSS names it. Left transparent by default, so the page shows through.
Color of the drop shadow lifting the window off the page, as CSS names it. Pass none to draw no shadow. Defaults to the one the chrome calls for.
Transparent pixels left around the window, on all four sides. The room the drop shadow falls into, so a capture drawing one wants some.
Pixels added inside the window, around the drawn text, on top of the few the renderer adds on its own.
How solid the window's body is. Under 1 it turns see-through, the way a terminal set to transparency does: whatever the capture sits on shows through it, while its text, frame and title bar keep their own paint.
Credit line drawn in the image's bottom-right corner, in the margin around the window. Pass an empty string to draw none, or your own text to credit your project instead.
Color that credit line is drawn in, as CSS names it, alpha included. Defaults to a neutral gray: the line sits in the transparent margin, so it answers to the page embedding the image rather than to the chrome.
Keep only the first N lines.
Keep only the last N lines.
Line standing in for what --head or --tail cut away.
Number the drawn lines in a gutter, the way Pygments does inline. Line 1 is the first line the picture shows.
Draw a band behind the lines named, as 2,4-5. Counted from 1 as the picture draws them. Ranges are closed: state both ends.
Caption drawn in an SVG's window chrome, or an HTML document's title.
For HTML, emit the bare block instead of a standalone document, to paste into a page that has its own.
Command line to display above the output, when it differs from the one that is run. Pass an empty string to draw no prompt at all. Defaults to the command line itself.
Fold the command's stderr into the capture, for a CLI printing its help there. Off by default, which is what keeps a wrapper's build chatter out of the image.
Route COMMAND_LINE through the wrap subcommand, so a Click CLI that is not built on Click Extra is captured with its colors. Only works on a target wrap can resolve.
Seconds before the command is killed. Waits forever by default. With --record, this is also where the recording stops.
Run the command under a pseudo-terminal and write an animated SVG of the screens it draws, spinners and progress bars included. Needs an .svg --output and a numeric --columns. Unix only.
With --record, the height of the terminal the command runs in, in characters. Defaults to 24.
With --record, extra seconds the last frame stays up before the animation starts over, or auto to scale them to that frame's line count. Defaults to auto.
With --record, seconds of empty screen closing the cycle. Defaults to 0.6.
Draw a terminal cursor where the command left it. Bare, it takes the shape the --preset terminal draws; name one to override that. Omitted, no cursor is drawn.
With --cursor, seconds one blink takes. Pass 0 to draw a steady cursor. Defaults to 1.0.
Draw the shell's prompt on the row under the output, where it comes back once the command exits. Costs no height alongside --cursor, which already leaves that row for the cursor to wait on.
With --record, open the animation by typing the command line out, this many seconds per character. Omitted, the prompt stands there from the first frame.
With --typing, seconds the finished command line waits before its output starts. Defaults to 0.4.
With --record, how much faster to play than recorded: 2 halves every frame's time. Defaults to 1.0.
Show this message and exit.

Location of the configuration file. Supports local path with glob patterns or remote URL.
Ignore all configuration files and only use command line parameters and environment variables.
Validate the configuration file and exit.
Export the configuration in the selected format to <stdout>, then exit.
[values: toml, yaml, json, json5, jsonc, hjson, xml, plist]

Accessibility mode: disable colors and render tables in a borderless, screen-reader-friendly format.
Colorize the output. A bare --color is the same as --color=always.
Disable colorization (alias of --color=never).
Show progress indicators during long operations. Disabled for non-interactive output (pipes, dumb terminals, CI) and by --accessible.
Color theme used for help screens.
Rendering style of tables.
[values: aligned, asciidoc, colon-grid, csv, csv-excel, csv-excel-tab, csv-unix, double-grid, double-outline, fancy-grid, fancy-outline, github, grid, heavy-grid, heavy-outline, hjson, html, jira, json, json5, jsonc, latex, latex-booktabs, latex-longtable, latex-raw, mediawiki, mixed-grid, mixed-outline, moinmoin, orgtbl, outline, pipe, plain, presto, pretty, psql, rounded-grid, rounded-outline, rst, simple, simple-grid, simple-outline, textile, toml, tsv, unsafehtml, vertical, xml, yaml, youtrack]

Either CRITICAL, ERROR, WARNING, INFO, DEBUG.
[values: CRITICAL, ERROR, WARNING, INFO, DEBUG]
Increase the default WARNING verbosity by one level for each additional repetition of the option.
Decrease the default WARNING verbosity by one level for each additional repetition of the option.
Shorthand for --verbosity DEBUG.

Measure and print elapsed execution time.
Show all CLI parameters, their provenance, defaults and value, then exit.
Show the tree of nested subcommands and exit.
Read the command's manual page and exit.
Render the command in the given format and exit.
Show the version and exit.

Path of the file to write. Its extension picks the format: .svg for an image, .html for selectable text, .ansi for the escape sequences themselves. Pass - to print those to the terminal, which draws no window.
Terminal width, in characters, the command wraps its output to and the image is laid out at. Pass auto to pin neither: the command finds its own width, and the image is laid out at the longest line it printed, so nothing folds inside the picture.
Terminal chrome the capture is drawn on, and the palette its colors resolve against. Match it to the theme the captured CLI renders with: a light-background theme washes out on the dark default.
Terminal to draw the capture as: its window decorations, palette, font and prompt sigil. Anything stated alongside wins over it. Left out, the capture keeps the renderer's own neutral window.
Color of the frame drawn around the terminal window, as CSS names it. Pass none to draw no frame. Defaults to the one the chrome can show.
Thickness of that frame, in pixels.
How round the window's corners are, in pixels. Zero squares them. Defaults to 8, or to the rounding --preset terminal draws.
Color filling the image behind the window, margin included, as CSS names it. Left transparent by default, so the page shows through.
Color of the drop shadow lifting the window off the page, as CSS names it. Pass none to draw no shadow. Defaults to the one the chrome calls for.
Transparent pixels left around the window, on all four sides. The room the drop shadow falls into, so a capture drawing one wants some.
Pixels added inside the window, around the drawn text, on top of the few the renderer adds on its own.
How solid the window's body is. Under 1 it turns see-through, the way a terminal set to transparency does: whatever the capture sits on shows through it, while its text, frame and title bar keep their own paint.
Credit line drawn in the image's bottom-right corner, in the margin around the window. Pass an empty string to draw none, or your own text to credit your project instead.
Color that credit line is drawn in, as CSS names it, alpha included. Defaults to a neutral gray: the line sits in the transparent margin, so it answers to the page embedding the image rather than to the chrome.
Keep only the first N lines.
Keep only the last N lines.
Line standing in for what --head or --tail cut away.
Number the drawn lines in a gutter, the way Pygments does inline. Line 1 is the first line the picture shows.
Draw a band behind the lines named, as 2,4-5. Counted from 1 as the picture draws them. Ranges are closed: state both ends.
Caption drawn in an SVG's window chrome, or an HTML document's title.
For HTML, emit the bare block instead of a standalone document, to paste into a page that has its own.
Command line to display above the output, when it differs from the one that is run. Pass an empty string to draw no prompt at all. Defaults to the command line itself.
Fold the command's stderr into the capture, for a CLI printing its help there. Off by default, which is what keeps a wrapper's build chatter out of the image.
Route COMMAND_LINE through the wrap subcommand, so a Click CLI that is not built on Click Extra is captured with its colors. Only works on a target wrap can resolve.
Seconds before the command is killed. Waits forever by default. With --record, this is also where the recording stops.
Run the command under a pseudo-terminal and write an animated SVG of the screens it draws, spinners and progress bars included. Needs an .svg --output and a numeric --columns. Unix only.
With --record, the height of the terminal the command runs in, in characters. Defaults to 24.
With --record, extra seconds the last frame stays up before the animation starts over, or auto to scale them to that frame's line count. Defaults to auto.
With --record, seconds of empty screen closing the cycle. Defaults to 0.6.
Draw a terminal cursor where the command left it. Bare, it takes the shape the --preset terminal draws; name one to override that. Omitted, no cursor is drawn.
With --cursor, seconds one blink takes. Pass 0 to draw a steady cursor. Defaults to 1.0.
Draw the shell's prompt on the row under the output, where it comes back once the command exits. Costs no height alongside --cursor, which already leaves that row for the cursor to wait on.
With --record, open the animation by typing the command line out, this many seconds per character. Omitted, the prompt stands there from the first frame.
With --typing, seconds the finished command line waits before its output starts. Defaults to 0.4.
With --record, how much faster to play than recorded: 2 halves every frame's time. Defaults to 1.0.
Show this message and exit.
Location of the configuration file. Supports local path with glob patterns or remote URL.
Validate the configuration file and exit.
Export the configuration in the selected format to <stdout>, then exit.
Accessibility mode: disable colors and render tables in a borderless, screen-reader-friendly format.
Colorize the output. A bare --color is the same as --color=always.
Disable colorization (alias of --color=never).
Show progress indicators during long operations. Disabled for non-interactive output (pipes, dumb terminals, CI) and by --accessible.
Color theme used for help screens.
Rendering style of tables.
Either CRITICAL, ERROR, WARNING, INFO, DEBUG.
Increase the default WARNING verbosity by one level for each additional repetition of the option.
Decrease the default WARNING verbosity by one level for each additional repetition of the option.
Shorthand for --verbosity DEBUG.
Measure and print elapsed execution time.
Show all CLI parameters, their provenance, defaults and value, then exit.
Show the tree of nested subcommands and exit.
Read the command's manual page and exit.
Render the command in the given format and exit.
Show the version and exit.

~/.config/click-extra/{*.toml,*.yaml,*.yml,*.json,*.json5,*.jwcc,*.jsonc,*.hjson,*.ini,*.xml,*.plist,*.sqlite,*.sqlite3,*.conf,pyproject.toml}

0
Success.
1
A runtime error, or an aborted prompt (Ctrl-C, a declined confirmation).
2
A usage error: unknown option, invalid value, missing operand, or an unparsable configuration file.

Kevin Deldycke

2026-09-09 9.1.1.dev0