Command-Line Usage

The hpy command is the main interface for interacting with hpy-tool. Here's a breakdown of the available commands and options.

$ hpy --help

usage: hpy [-h] [--init PROJECT_DIR] [-o DIR] [-v] [-s] [-p PORT] [-w] [--version] [SOURCE]

HPY Tool: Compile/serve .hpy projects. Configurable via hpy.toml.

positional arguments:
  SOURCE                Path to source .hpy file or directory.
                        (default: 'src' from hpy.toml or built-in)

options:
  -h, --help            show this help message and exit
  --init PROJECT_DIR    Initialize a new HPY project structure (creates hpy.toml). Ignores SOURCE.
  -o DIR, --output-dir DIR
                        Directory for compiled output.
                        (overrides hpy.toml, default: 'dist' from hpy.toml or built-in)
  -v, --verbose         Enable detailed output.
  -s, --serve           Start a dev server serving the output directory.
  -p PORT, --port PORT  Port for the development server.
                        (default: 8000)
  -w, --watch           Watch source for changes and rebuild/sync. Requires 'watchdog'.
                        Using -w implies -s and uses the effective input/output dirs.
  --version             show program's version number and exit

Positional Arguments

• SOURCE (Optional)
  • Specifies the path to the source .hpy file or directory to process.
  • If omitted, the tool looks for the input_dir setting in hpy.toml.
  • If also not found in hpy.toml, it defaults to "src".
  • If a file is provided (e.g., hpy page.hpy), only that file is compiled, and layout/static handling are **not** automatically applied.
  • If a directory is provided (e.g., hpy app_source), the entire directory is processed according to layout and static asset rules.

Options

• -h, --help
  • Shows the help message and exits.
• --init PROJECT_DIR
  • Initializes a new project skeleton in the specified PROJECT_DIR.
  • Prompts for a template choice (Single File or Directory/Layout).
  • Creates necessary files, including hpy.toml.
  • Ignores the optional SOURCE argument if provided.
• -o DIR, --output-dir DIR
  • Specifies the directory where compiled HTML and static assets should be placed.
  • This **overrides** the output_dir setting in hpy.toml.
  • If omitted, the value from hpy.toml is used (defaulting to "dist" if not set there either).
• -v, --verbose
  • Enables detailed logging during build, watch, and server operations. Useful for debugging.
• -s, --serve
  • Starts a simple development HTTP server after the build finishes (if applicable).
  • Serves files from the determined output directory.
  • Automatically adds no-cache headers.
  • Note: Using -w implicitly enables -s.
• -p PORT, --port PORT (Default: 8000)
  • Specifies the port number for the development server (used with -s or -w).
• -w, --watch
  • Enables watch mode (requires the watchdog library).
  • Performs an initial build.
  • Starts the development server (implicitly enables -s).
  • Monitors the source directory (including static subdirectory if enabled) for changes.
  • Automatically rebuilds .hpy files or syncs static assets upon changes.
  • Uses the effective input and output directories determined by CLI args, hpy.toml, or defaults.
• --version
  • Shows the installed hpy-tool version and exits.

Common Usage Examples

# Initialize a new project in 'my_app' directory
hpy --init my_app

# Build the project using settings from hpy.toml (e.g., src -> dist)
hpy

# Build the project, overriding the output directory
hpy -o build

# Build using a specific source directory, overriding output
hpy app_source -o public

# Build only a single file (no layout/static handling) into 'dist'
hpy src/pages/contact.hpy

# Build project and serve from the output directory on default port 8000
hpy -s

# Build project, watch for changes, and serve on port 8080
# (Uses input/output from hpy.toml or defaults)
hpy -w -p 8080

# Watch only a single file (no layout/static handling) and serve its output
# (Output placed in 'dist/single.html' by default, server serves 'dist')
hpy src/single.hpy -w