DOCSEARCHbyAlgolia
Submit Docs

termshot

repository·main·Indexed 21 days ago

https://github.com/homeport/termshot

A CLI tool that executes terminal commands and captures their output as high-quality, stylized PNG screenshots. It supports pseudo-terminal execution, raw input from files or stdin, manual editing of output via $EDITOR, and customizable window decorations, margins, and padding.

Tokens
1K
Snippets
4
Records
4
Agent score
26%

What's inside termshot

  1. Distinguish between termshot flags and command flags

    main

    Because termshot executes other commands, you may need to pass flags to the underlying command that conflict with termshot's own flags. To ensure flags are interpreted correctly, use the -- separator.

    Flags appearing before -- are interpreted by termshot. Flags appearing after -- are passed directly to the command being executed.

    # termshot uses --margin, but the 'ls' command doesn't. 
# This is correct:
termshot --margin 10 ls -la

# If you want to pass a flag to the command being run:
termshot -- ls -la --color

  2. Use termshot to create terminal screenshots

    main

    termshot executes a command in a pseudo-terminal, captures its output, and renders it into a high-quality image that looks like a terminal window. It supports terminal colors and text decorations.

    Basic Usage: To capture the output of a command, pass the command and its arguments directly:

    termshot ls -la

    Key Features:

    • Command Execution: Runs commands in a pseudo-terminal to capture real output.
    • Raw Input: Instead of running a command, you can read content from a file or stdin using --raw-read.
    • Manual Editing: Use the --edit flag to open the captured output in your $EDITOR before the screenshot is generated.
    • Output Formats: By default, it saves a PNG file. You can also use --raw-write to save the plain text output instead of an image.
    termshot <command> [args] [flags]
# Example: capture 'ls -la' output
termshot ls -la

# Example: read from a file instead of executing
termshot --raw-read my_output.txt

# Example: save raw text output to a file
termshot ls -la --raw-write output.txt

  3. Configure termshot output and raw processing

    main

    Control how the results are saved or how input is ingested:

    FlagShorthandTypeDescription
    --filename-fstringThe filename for the PNG screenshot. Defaults to out.png.
    --clipboard(none)boolSave the generated image directly to the system clipboard.
    --raw-read(none)stringRead raw input from a file or - (for stdin) instead of executing a command.
    --raw-write(none)stringWrite the raw text output to a file or - (for stdout) instead of creating a screenshot.
    # Save screenshot to a specific file
termshot ls -la -f my_screenshot.png

# Pipe input to termshot and save screenshot to clipboard
cat log.txt | termshot --raw-read - --clipboard

# Capture command output as raw text instead of an image
termshot ls -la --raw-write output.log

  4. Configure termshot screenshot appearance

    main

    You can customize the visual style of the generated terminal window using several flags:

    FlagShorthandTypeDescription
    --columns-CintForce a fixed number of columns for text wrapping.
    --margin-mintSet the margin (in pixels) around the window. Default is 48.
    --padding-pintSet the padding (in pixels) inside the window. Default is 24.
    --no-decoration(none)boolDo not draw window decorations (buttons).
    --no-shadow(none)boolDo not draw the window shadow.
    --clip-canvas-sboolClip the canvas to the visible image area (removes margin).
    --show-cmd-cboolPrepend the executed command to the output content in the screenshot.
    termshot ls -la --margin 10 --padding 5 --no-shadow --show-cmd