clishot

中文 README

clishot generates pseudo-terminal screenshots by executing real terminal commands defined in YAML workflows on your local machine. Ideal for agent automation workflows.

clishot is built on top of termless and uses termless core as its terminal automation and rendering engine. Sincerely thank the termless project and its contributors.

Why clishot?

• Full terminal customization — works with OhMyPosh, OhMyZSH, Starship, and any shell theme or plugin you already use.
• True ANSI parsing — reads real ANSI escape sequences from your terminal, not pixel-level screenshot stitching.
• Built for agents — YAML-driven, headless, and deterministic; designed from the ground up for AI agent automation workflows.

Examples

These images are generated by clishot itself, built from byte streams of real terminal sessions.

Quick Start From The Repo

You can clone it, install dependencies, build the CLI, and run one of the included examples:

git clone <repo-url> clishot
cd clishot
npm install
npm run build
node dist/cli/index.js doctor
node dist/cli/index.js record examples/hello.yml --out tmp/hello.png --force

The generated image will be written to tmp/hello.png. Internal debug artifacts are written under tmp/tmp-* and are ignored by Git.

During development you can also link the local CLI:

npm link
clishot doctor
clishot record examples/hello.yml --out tmp/hello.png --force

Install As A CLI

npm install -g clishot

If you installed from npm, use the clishot command directly:

clishot doctor
clishot record examples/hello.yml --out tmp/hello.png --force

Basic Usage

clishot record examples/hello.yml --out figures/hello.png
clishot validate examples/hello.yml
clishot doctor
clishot version

record always requires --out. The final image path belongs to the CLI, not the YAML file.

YAML Example

shell:
  program: pwsh
  args: ["-NoLogo"]

terminal:
  cols: 100
  rows: 30

appearance:
  output:
    scale: 2

capture:
  mode: fullScrollback

steps:
  - type: send
    text: "python --version"
    enter: true
    waitFor:
      idleMs: 800

For the full specification see SPEC and SKILL.md.

Commands

clishot record <spec-file> --out <output-file>
clishot validate <spec-file> [--check-runtime]
clishot doctor
clishot version
clishot inspect <capture-dir>
clishot clean <capture-dir>

Supported output formats are png, jpg, jpeg, webp, and svg. The default is png; if the output extension differs, pass an explicit --format.

clishot record demo.yml --out figures/demo.webp --format webp

Screenshot steps write named intermediate screenshots:

steps:
  - type: send
    text: "gcc main.c -o main"
    enter: true
    waitFor:
      idleMs: 800
  - type: screenshot
    name: "after-compile"

clishot record demo.yml --out figures/final.png --shots-dir figures/steps

Error Policy

Errors printed by commands inside the terminal are terminal content, not clishot failures. For example, a compiler error or Python traceback should still be captured.

clishot fails for configuration errors, shell startup failure, wait timeouts, termless core unavailability, render failures, and output write failures. Failed runs keep tmp/tmp-<timestamp>-<spec>/ debug artifacts.

Cross Platform Notes

Windows defaults to pwsh -NoLogo when no shell is configured. Linux and macOS use $SHELL or bash. WSL is supported through explicit shell.program: wsl.exe configuration.

Agent Skill

This repository includes an Agent-facing Skill at skills/clishot/SKILL.md. Use it when an AI agent needs to generate clishot YAML, run clishot record, insert screenshots into reports, or debug failed captures.

The Skill is guidance only; it does not add runtime features. Human users can read it as a compact workflow guide, while agents should follow it together with docs/SPEC.md and docs/git-rule.md when working in this repository.

License

MIT