CLI Overview

cli overview installation commands dashboard pack

CLI Overview

The huitzo CLI is the primary tool for developing, testing, and managing both Intelligence Packs and Dashboards. It provides a unified developer experience across both domains: server-side business logic (packs) and client-side user interfaces (dashboards).

Installation

The huitzo CLI ships as a native launcher (a small Rust binary) that manages a private Python virtual environment at ~/.huitzo/venv/ and keeps the CLI up to date in the background. Direct pip install is not a supported install path — always go through the launcher.

# pseudocode — install the CLI

# Homebrew (macOS)
brew install Huitzo-Inc/tap/huitzo

# curl (Linux / macOS)
curl -sSf https://raw.githubusercontent.com/Huitzo-Inc/huitzo-launcher/main/install.sh | sh

# Verify installation
huitzo --version

For Windows, manual binaries, or launcher-specific flags (--launcher-version, --launcher-bootstrap, --launcher-update), see the Huitzo Launcher README.

Design Philosophy

Progressive Disclosure

Commands start simple and add complexity only when needed. huitzo pack new my-pack and huitzo dashboard new my-dashboard scaffold working projects with zero configuration. Advanced options (--template, --namespace, --visibility) are available but never required.

10-Minute Test

A developer should go from zero to a running pack or dashboard in under 10 minutes. The scaffold templates include everything needed to build, run, and validate locally without external services.

Convention Over Configuration

Sensible defaults everywhere: React + TypeScript for dashboards, Python for packs, Vite library mode for dashboard builds, standard directory layouts. Override only when you have a reason to.

Agent & Automation

Every command supports dual-mode output. By default, the CLI renders human-friendly terminal formatting with spinners and color. When --output json is passed, it emits a structured JSON envelope ({"ok": true, "data": {...}} or {"ok": false, "error": {...}}) suitable for AI agents and CI/CD pipelines. The --non-interactive flag suppresses prompts and confirmations, and is implied automatically in JSON mode. See Agent Integration for the full specification.

Two Domains: Packs and Dashboards

The CLI manages two artifact types. A third command group — huitzo project ... — is a small set of scaffolding helpers for fullstack apps that bundle a Pack and a Dashboard in one directory. It is a convenience; the Pack and Dashboard groups remain the primary CLI surface.

Aspect Intelligence Pack (huitzo pack ...) Dashboard (huitzo dashboard ...)
Role Server-side business logic Client-side UI inside Hub
Language Python TypeScript (React)
Manifest huitzo.yaml huitzo-dashboard.yaml
Build output Python package dist/main.js (self-contained ESM module)
Execution Server-side (Huitzo workers) Client-side (browser, inside Hub)
Entry contract @command decorated functions mount(container, context) / unmount(container) exports
Canonical reference Pack Manifest Dashboard Overview

Both domains follow the same lifecycle. For fullstack apps, huitzo project init scaffolds a folder that holds both — see Intelligence Projects.

Shared Lifecycle

new  →  dev  →  build  →  validate  →  publish  →  grant/share  →  uninstall
 │       │       │          │            │            │                │
 │       │       │          │            │            │                └─ Remove pack, commands + grants (cloud)
 │       │       │          │            │            └─ Access control (cloud)
 │       │       │          │            └─ Upload to registry (cloud)
 │       │       │          └─ Check manifest + output (local)
 │       │       └─ Production build (local)
 │       └─ Local dev server with hot reload (local)
 └─ Scaffold project from template (local)

Local commands (new, dev, build, validate) work offline without authentication. Cloud commands (publish, grant, revoke, share, uninstall) require Huitzo Cloud authentication.

Authentication

Command Group Authentication Required
new, dev, build, validate No — fully local
publish Yes — uploads to registry
grant, revoke, share Yes — modifies access control
login, logout N/A — manages credentials 
# pseudocode — authenticate with Huitzo Cloud

huitzo login          # Opens browser for OAuth flow
huitzo logout         # Clears stored credentials

Credentials are stored in ~/.config/huitzo/config.toml (Linux/macOS) or %APPDATA%\huitzo\config.toml (Windows). The HUITZO_TOKEN environment variable overrides stored credentials.

Global Options

Option Short Description
--help -h Show help message
--version -V Show CLI version
--verbose -v Enable verbose output
--quiet -q Suppress non-error output
--config -c Path to config file

Command Groups

Project Commands (Scaffolding Only)

Scaffold a fullstack app folder that holds a Pack and a Dashboard side-by-side. Three commands — everything else uses the Pack and Dashboard CLI groups from inside the relevant subdirectory.

Command Description
huitzo project init <name> Create the Project directory. Prompts interactively to add a Dashboard.
huitzo project add-pack Populate pack/ in a Project that started Dashboard-only
huitzo project add-dashboard Add dashboard/ to a Project that started pack-only

See CLI Reference — Project Commands and Authoring an Intelligence Project.

Pack Commands

Develop and manage Intelligence Packs (server-side Python business logic).

Command Description
huitzo pack new Scaffold a new pack project
huitzo pack dev Start local development server
huitzo pack run Execute a pack command
huitzo pack build Build pack for distribution
huitzo pack test Run pack test suite
huitzo pack validate Validate manifest and structure
huitzo pack sync Regenerate pyproject.toml from huitzo.yaml
huitzo pack publish Publish to registry

See CLI Reference — Pack Commands for full details.

Dashboard Commands

Develop and manage Dashboards (client-side React micro-frontends that run inside Hub).

Command Description
huitzo dashboard new Scaffold a new dashboard project
huitzo dashboard dev Start Vite dev server with mock Hub context
huitzo dashboard build Build self-contained ESM module
huitzo dashboard validate Validate manifest and build output
huitzo dashboard publish Publish to Huitzo Hub (cloud-gated)
huitzo dashboard grant Grant organization access (cloud-gated)
huitzo dashboard revoke Revoke organization access (cloud-gated)
huitzo dashboard share Generate shareable link (cloud-gated)

See CLI Reference — Dashboard Commands for the command reference, or Dashboard CLI Guide for the end-to-end workflow.

Utility Commands

Command Description
huitzo login Authenticate with Huitzo Cloud
huitzo logout Clear stored credentials
huitzo config View or edit CLI configuration
huitzo mcp Manage MCP server connections
huitzo sandbox start/stop/status Manage local sandbox lifecycle

See CLI Reference for the complete command reference.