CLI Reference

CLI reference

Dev Reel provides a simple CLI with few commands. The interface is designed to be intuitive and requires minimal configuration.

Installation and usage

You can use Dev Reel in three ways:

bash

# Via npx (no installation)
npx @promise-inc/dev-reel build

# Installed globally
npm install -g @promise-inc/dev-reel
dev-reel build

# As dev dependency
npm install --save-dev @promise-inc/dev-reel
npm run build:reels  # via package.json script

dev-reel build

Main command. Processes README.md and generates SVG files.

bash

dev-reel build [options]

Behavior:

Looks for README.md in current directory root
Finds all code blocks with language 'dev-reel'
Parses YAML frontmatter from each block
Generates SVG files in assets/ (creates directory if it doesn't exist)
Filename based on block 'title' option
Overwrites existing files

Example output:

bash

$ npx @promise-inc/dev-reel build

✔ Found 3 dev-reel blocks in README.md
✔ Generated assets/installation.svg (3.8 KB)
✔ Generated assets/quick-start.svg (4.2 KB)
✔ Generated assets/example.svg (5.1 KB)
✔ Build completed in 0.4s

Options

--watch

Watch mode. Monitors README.md changes and automatically rebuilds.

bash

dev-reel build --watch

Behavior in watch mode:

Performs initial build
Monitors README.md for changes
Automatic rebuild when file is saved
Log output for each rebuild
Continues running until Ctrl+C

Output:

bash

$ npx @promise-inc/dev-reel build --watch

✔ Found 3 dev-reel blocks in README.md
✔ Generated assets/installation.svg (3.8 KB)
✔ Build completed in 0.4s
👀 Watching README.md for changes...

# [you edit README.md]

🔄 README.md changed, rebuilding...
✔ Found 3 dev-reel blocks in README.md
✔ Generated assets/installation.svg (4.1 KB)
✔ Build completed in 0.3s
👀 Watching README.md for changes...

Watch mode is ideal for iterative development. Edit the README and see SVGs update automatically.

--dry-run

Preview without writing files. Shows what would be generated without creating SVGs.

bash

dev-reel build --dry-run

Behavior:

Parses all blocks
Validates frontmatter
Shows list of files that would be generated
Shows estimated sizes
Does NOT create SVG files
Does NOT create assets/ directory

Output:

bash

$ npx @promise-inc/dev-reel build --dry-run

✔ Found 3 dev-reel blocks in README.md

Would generate:
  • assets/installation.svg (~3.8 KB)
  • assets/quick-start.svg (~4.2 KB)
  • assets/example.svg (~5.1 KB)

Total: 3 files (~13.1 KB)

👍 Dry run complete (no files written)

Use cases:

Verify syntax without generating files
Preview before commit
CI checks (validate blocks without creating artifacts)
Configuration debugging

--help

Shows help and command list.

bash

dev-reel --help
dev-reel build --help

--version

Shows installed version.

bash

dev-reel --version

Directory structure

Dev Reel assumes and creates the following structure:

bash

project/
├── README.md          # Source with dev-reel blocks
└── assets/            # Created automatically
    ├── demo.svg
    ├── installation.svg
    └── example.svg

Directory behavior:

README.md MUST be in the root where you execute the command
assets/ is created automatically if it doesn't exist
SVG files are named based on 'title' option
Existing files are overwritten without warning
No support for custom paths (always assets/)

Exit codes

The CLI returns exit codes for use in scripts:

Code	Meaning
0	Success
1	Generic error (build failure)
2	README.md not found
3	No dev-reel blocks found
4	Frontmatter parsing error
5	File write error

Script usage:

bash

#!/bin/bash
npx @promise-inc/dev-reel build
if [ $? -eq 0 ]; then
  echo "Build succeeded"
  git add assets/*.svg
else
  echo "Build failed"
  exit 1
fi

CI/CD usage

Pipeline integration examples:

GitHub Actions:

yaml

name: Generate Dev Reels
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 18
      - run: npx @promise-inc/dev-reel build
      - name: Commit SVGs
        run: |
          git config user.name "GitHub Actions"
          git config user.email "actions@github.com"
          git add assets/*.svg
          git diff --quiet || git commit -m "chore: update dev-reel SVGs"
          git push

GitLab CI:

yaml

generate-reels:
  image: node:18
  script:
    - npx @promise-inc/dev-reel build
  artifacts:
    paths:
      - assets/*.svg

Package.json scripts:

json

{
  "scripts": {
    "build:reels": "dev-reel build",
    "dev:reels": "dev-reel build --watch",
    "validate:reels": "dev-reel build --dry-run",
    "prebuild": "npm run build:reels"
  },
  "devDependencies": {
    "@promise-inc/dev-reel": "^1.0.1"
  }
}

Troubleshooting

Common problems and solutions:

Problem	Solution
README.md not found	Execute command at project root where README.md is located
No dev-reel blocks found	Verify your blocks use ```dev-reel and not ```bash or another language
Invalid frontmatter	Validate YAML syntax. Use --dry-run to see detailed errors
Permission denied writing to assets/	Check directory permissions. Execute with sudo if necessary
SVG doesn't appear on GitHub	GitHub may cache. Force refresh (Ctrl+F5) or wait a few minutes

Tips and best practices

Use --dry-run before commits to validate blocks
Use --watch during development for immediate feedback
Add assets/*.svg to .gitignore if you generate SVGs in CI
Or commit SVGs for GitHub to display without build
Add npm run build:reels to your pre-commit hook
Use descriptive titles (installation, not demo1)
Document in README that SVGs are auto-generated

Complete workflow example

bash

# 1. Install as dev dependency
npm install --save-dev @promise-inc/dev-reel

# 2. Add script to package.json
npm pkg set scripts.build:reels="dev-reel build"
npm pkg set scripts.dev:reels="dev-reel build --watch"

# 3. Develop with watch mode
npm run dev:reels
# Edit README.md, see SVGs update

# 4. Validate before commit
npx dev-reel build --dry-run

# 5. Final build
npm run build:reels

# 6. Commit
git add README.md assets/*.svg
git commit -m "docs: add terminal previews"
git push

For large projects, consider using CI to generate SVGs automatically when merging to main, keeping branches clean.

Animations