CLI Usage¶

The zipreport CLI tool provides commands for building, inspecting, and debugging report templates.

Commands¶

build¶

Build a .zpt file from a template directory.

zipreport build <source_dir> <output.zpt>

Arguments:

source_dir - Path to the template directory
output.zpt - Output filename

Flags:

-s, --symlinks - Follow symlinks when building

Examples:

# Build from directory
zipreport build ./my-template output.zpt

# Follow symlinks
zipreport build -s ./my-template output.zpt

Requirements:

The source directory must contain:

manifest.json - Report metadata
index.html - Main template file

debug¶

Start a development HTTP server that renders the template on each request.

zipreport debug <source>

Arguments:

source - Template directory or .zpt file

Flags:

-p, --port - Port to listen on (default: 8000)

Examples:

# Debug a directory
zipreport debug ./my-template

# Debug a .zpt file
zipreport debug report.zpt

# Use custom port
zipreport debug -p 3000 ./my-template

The debug server:

Reloads the template on each request (no restart needed)
Serves static assets (CSS, JS, images)
Uses data from data.json if present
Shows render errors in the browser

info¶

Display metadata from a .zpt file.

zipreport info <report.zpt>

Arguments:

report.zpt - Path to the .zpt file

Output:

Report: report.zpt
----------------------------------------
Title:       My Report
Author:      John Doe
Version:     1.0.0
Description: A sample report
Parameters:  name, items
Use JS Event: false

list¶

List .zpt files in a directory.

zipreport list [directory]

Arguments:

directory - Directory to search (default: current directory)

Examples:

# List in current directory
zipreport list

# List in specific directory
zipreport list ./reports

version¶

Display the CLI version.

zipreport version

Global Flags¶

--help, -h - Show help for any command

Template Structure¶

A valid template directory must contain:

template/
├── manifest.json    # Required: Report metadata
├── index.html       # Required: Main template
├── data.json        # Optional: Default data for debugging
├── style.css        # Optional: Stylesheets
├── script.js        # Optional: JavaScript
└── images/          # Optional: Static assets
    └── logo.png

manifest.json¶

{
    "title": "Report Title",
    "author": "Author Name",
    "version": "1.0.0",
    "description": "Report description",
    "params": ["param1", "param2"],
    "report": "report.html",
    "useJSEvent": false
}

Field	Required	Description
`title`	Yes	Report title
`author`	Yes	Author name
`version`	Yes	Version string
`description`	Yes	Report description
`params`	Yes	Required template parameters (can be `[]`)
`report`	No	Output filename (default: `report.html`)
`useJSEvent`	No	Wait for JS event (default: `false`)

data.json¶

Optional file containing default data for debugging:

{
    "param1": "value1",
    "param2": ["item1", "item2"]
}

Examples¶

Development Workflow¶

# 1. Create template directory
mkdir my-report
cd my-report

# 2. Create required files
echo '{"title":"My Report","author":"Me","version":"1.0.0","description":"Test","params":[]}' > manifest.json
echo '<h1>Hello World</h1>' > index.html

# 3. Start debug server
zipreport debug .

# 4. Edit templates, refresh browser to see changes

# 5. Build final .zpt
zipreport build . ../my-report.zpt

# 6. Verify
zipreport info ../my-report.zpt