CLI Reference¶

The hbia command-line tool provides commands for scaffolding, execution, validation, inspection, and management of HBIA projects.

Installation¶

pip install honey-badgeria[cli]

Project Management¶

init¶

Scaffold a new HBIA project.

hbia init <name> [--framework plain|fastapi|monorepo]

Argument	Description
`<name>`	Project directory name
`--framework`	Project type: `plain` (default), `fastapi`, `monorepo`

Examples:

hbia init my_project                        # Plain backend project
hbia init my_api --framework fastapi        # FastAPI project
hbia init my_app --framework monorepo       # Full-stack monorepo

version¶

Show the installed HBIA version.

hbia version

doctor¶

Check your environment for correct setup.

hbia doctor

Verifies: Python version, installed packages, available extras, configuration validity.

health¶

Scan the project for tech debt and structural issues.

hbia health

Checks: module line counts, vertex counts per flow, configuration completeness.

Backend Commands¶

run¶

Execute a flow.

hbia run <flow.yaml> --handlers <module>

Argument	Description
`<flow.yaml>`	Path to flow definition file
`--handlers`	Python module containing handler functions

validate¶

Check YAML syntax and DSL structure.

hbia validate <flow.yaml>

graph-validate¶

Check graph structural integrity (cycles, missing edges, atomic groups).

hbia graph-validate <flow.yaml>

inspect¶

Show topology, execution stages, and vertex details.

hbia inspect <flow.yaml>
hbia inspect <flow.yaml> --json      # Machine-readable output

explain¶

Generate a human-readable description of the flow.

hbia explain <flow.yaml>

lint¶

Check flows for AI best practices.

hbia lint <path>
hbia lint <path> --strict            # Treat warnings as errors

<path> can be a single YAML file or a directory of flows.

viz¶

Visualize the DAG.

hbia viz <flow.yaml>                 # Graphviz rendering (requires viz extra)
hbia viz <flow.yaml> --ascii         # ASCII art (no dependencies)

flow-list¶

List all flows found in the project.

hbia flow-list

Cache Commands¶

cache-info¶

Show cache statistics (entries, size).

hbia cache-info

cache-prune¶

Remove old cache entries.

hbia cache-prune

clear-cache¶

Delete all cached data.

hbia clear-cache

AI Context Commands¶

context¶

Generate or display AI context documentation.

hbia context --write                 # Write AGENTS.md to project root
hbia context --show                  # Display to stdout

The generated AGENTS.md file contains a complete description of the project architecture that AI agents read to understand the codebase.

Frontend Commands¶

ui-inspect¶

Inspect a frontend graph domain.

hbia ui-inspect graph/<domain>/

ui-graph¶

Show the structure of a frontend graph.

hbia ui-graph graph/<domain>/

ui-validate¶

Validate frontend YAML definitions.

hbia ui-validate graph/

ui-lint¶

Lint frontend graphs for best practices.

hbia ui-lint graph/

ui-codegen¶

Generate TypeScript runtime from frontend YAML definitions.

hbia ui-codegen graph/ --output <output_dir>

Argument	Description
`graph/`	Path to the graph definitions directory
`--output`	Output directory for generated TypeScript files

Example:

hbia ui-codegen graph/ --output front/hbia-runtime/

Generates: types.ts, store.ts, effects.ts, events.ts, react.tsx, index.ts.