GitHub - DeepGuide-Ai/dg: Self-testing CLI documentation tool that generates interactive demos

3 min read Original article ↗

DeepGuide CLI

Demo status npm version CI Status License: MIT

Transform your CLI documentation from static code blocks or heavy GIF/Video into self-testing, interactive, lightweight demos that stay current automatically.

Use dg to capture your terminal session

Captured using dg. We dogfood ourselves.

Capture - light Capture - dark

Installation

Via npm (recommended)

# Install globally
sudo npm install -g @deepguide-ai/dg

# Or run without installing
npx @deepguide-ai/dg init

Requirements

  • Node.js 18+ - The CLI runs on Node.js
  • termsvg - For recording terminal sessions (auto-installed on first use)

Verify Installation

This will check that all dependencies are properly installed.

Quick Start

npx @deepguide-ai/dg init  # 30-second setup
dg capture                 # Record interactive demo
dg validate                # Test in CI - PR fails if broken

Core Commands

Command Purpose Example
dg init Interactive setup wizard npx @deepguide-ai/dg init
dg capture Record CLI demos dg capture
dg validate Test demos in CI dg validate
dg list Show status dg list
dg doctor Environment diagnostics dg doctor

FAQ

Q: How does validation work?

A: DG re-runs your original commands and compares exit codes + filtered output. Interactive demos are automatically skipped in CI.

Q: What platforms are supported?

A: All platforms supported by Node.js 18+: macOS, Linux. Requires Node.js runtime. Windows is supported through WSL.

Q: How big are the generated assets?

A: SVG demos are typically 50-100x smaller than equivalent GIFs.

Examples in the Wild

See DG in action:

  • Demo - Demo Project for dg

Want your project listed? Open a PR!

Contributing

We welcome contributions! See our Contributing Guide.

Development Setup

git clone https://github.com/deepguide-ai/dg.git
cd dg
pnpm install
pnpm run build
pnpm run dev

Testing

pnpm test              # Unit tests (when available)
pnpm run build         # Build TypeScript
node dist/index.js    # Test built CLI

Support

  • 🐛 Issues - Bug reports and feature requests
  • 💬 Discussions - Questions and community
  • 📧 Email - Direct support

Credits

DeepGuide CLI builds upon these amazing open source projects:

  • asciinema - The core terminal session recorder that powers our demo capture. GPL-3.0 licensed.
  • node-pty - Pseudoterminal implementation that enables cross-platform terminal recording. MIT licensed.
  • termsvg - Terminal session to SVG renderer that creates our lightweight, beautiful demo outputs. GPL-3.0 licensed.

Special thanks to the maintainers and contributors of these projects! ❤️

License

MIT - The main CLI tool is MIT licensed for maximum compatibility.

Platform packages containing termsvg binaries are GPL-3.0 licensed. Enterprise users can avoid GPL binaries with DG_GPL_OFF=1.

Made with ❤️ by the DeepGuide team

Transform your CLI documentation from static to spectacular.