termframe

Turn any terminal command into a shareable SVG or HTML frame—without taking a screenshot, opening a browser, or uploading output anywhere.

npx --yes github:jovial-liu/termframe run \
  --title "npm test" \
  --out test.svg \
  -- npm test

The result is a standalone image that works in a README, GitHub issue, blog post, or chat. ANSI colors are preserved, output is escaped for SVG, and common token-shaped values are redacted by default.

When using run, the frame header also shows the wrapped command's exit code—for example, a red exit 7 on a failed CI artifact.

Why termframe?

termframe is for the moment after a command runs—not for recording a whole terminal session:

• no browser, Puppeteer, server, or network connection
• SVG is the default, so the artifact stays sharp in a README
• failed CI commands still produce an artifact before returning their exit code
• token-shaped output is redacted before it reaches the image
• the same renderer works as a CLI, a pipe, a Node library, or a GitHub Action

Render existing output

termframe render output.txt --format html --out output.html --theme light
cat output.txt | termframe render --out output.svg

Formats:

• svg — portable, dependency-free image for Markdown and the web
• html — a tiny self-contained page with responsive styling
• json — redacted lines and metadata for automation

Use it in CI

set +e
termframe run --out test-output.svg --title "CI failure" -- npm test
status=$?
set -e
echo "artifact: test-output.svg"
exit "$status"

Even when the command fails, termframe writes the artifact before returning the wrapped exit code. That makes it useful for CI artifacts and bug reports.

Or use the composite action:

- uses: jovial-liu/termframe@v1
  with:
    command: npm test
    output: test-output.svg
    title: CI test output
- uses: actions/upload-artifact@v4
  if: always()
  with:
    name: terminal-frame
    path: test-output.svg

Security

The child process receives a small environment containing PATH, terminal settings, and basic temporary-directory variables. Output never leaves the machine. Redaction is best-effort; review generated artifacts before publishing them.

Development

Requires Node.js 18+ and has no runtime dependencies.

npm test
npm run lint
node bin/termframe.mjs run --out demo.svg -- printf 'hello\n'

License

MIT © termframe contributors