CLI Reference

Last updated: 2026-05-07 06:53:50

cli commands terminal

Huitzo CLI Reference¶

The huitzo CLI is your primary tool for developing, testing, and managing Intelligence Packs and Dashboards. See CLI Overview for installation and design philosophy.

Installation¶

# Using uv (recommended)
uv pip install huitzo-cli

# Using pip
pip install huitzo-cli

# Verify installation
huitzo --version

Global Options¶

These options are available for all commands:

Option	Short	Description
`--help`	`-h`	Show help message
`--version`	`-V`	Show version
`--verbose`	`-v`	Enable verbose output
`--quiet`	`-q`	Suppress non-error output
`--config`	`-c`	Path to config file
`--output`	`-o`	Output format (`text`, `json`). JSON mode emits a structured envelope
`--non-interactive`		Suppress prompts, spinners, and confirmations. Implied by `--output json`

Project Commands¶

The huitzo project ... group is scaffolding only — three commands that set up a fullstack Project directory holding a Pack and (optionally) a Dashboard. Lifecycle work (dev, validate, build, publish, test) uses the existing Pack and Dashboard CLI groups, run from inside pack/ or dashboard/.

Canonical references: Intelligence Projects, Project Layout, Project Authoring.

`huitzo project init`¶

Scaffold a new Project directory.

# pseudocode
huitzo project init [OPTIONS] [NAME]

Argument	Required	Description
`NAME`	No	Project directory name (prompts if not provided). kebab-case.

Option	Default	Description
`--with-dashboard`	—	Scaffold `dashboard/` (skips the interactive prompt)
`--no-dashboard`	—	Do not scaffold `dashboard/` (skips the interactive prompt)
`--template`	`default`	Project template (`default`, `scheduled`, `mcp`)
`--non-interactive`	(implied by `--output json`)	Suppress prompts. Requires one of `--with-dashboard` / `--no-dashboard`.

Behavior:

Validates the name (kebab-case, 3-50 chars, no collision with existing directory).
Creates the Project directory.
Scaffolds pack/ via huitzo pack new.
If neither --with-dashboard nor --no-dashboard was passed, prompts: "Add a Dashboard to this Project? (y/N)". On y, scaffolds dashboard/ via huitzo dashboard new; on N or empty input, skips the Dashboard.
Seeds docs/ with placeholder spec.md, architecture.md, runbook.md — each with a traceability header stub.
Seeds .claude/ with Project-scoped rules and settings.
Writes README.md.

No Project-level manifest is written. The Pack and Dashboard manifests inside the subdirectories are the only manifests involved.

Exit codes: 0 success, 3 name validation error, 1 other errors.

`huitzo project add-pack`¶

Populate the pack/ subdirectory of an existing Project. Used when a Project was initialized Dashboard-only.

# pseudocode
huitzo project add-pack [OPTIONS]

Run from the Project root.

Option	Default	Description
`--template`	`basic`	Pack template (same values as `huitzo pack new --template`)
`--namespace`	(from Project directory name)	Pack namespace

Errors:

Error	Cause
`Pack already exists`	`pack/huitzo.yaml` is already present
`Not a Project directory`	Current directory is not a Project (no `pack/` or `dashboard/` subdirectory found)

Exit codes: 0, 3, 1.

`huitzo project add-dashboard`¶

Add a dashboard/ subdirectory to a Project that started pack-only.

# pseudocode
huitzo project add-dashboard [OPTIONS]

Run from the Project root.

Option	Default	Description
`--template`	`basic`	Dashboard template (same values as `huitzo dashboard new --template`)

Errors: same shape as add-pack (Dashboard already exists, Not a Project directory).

Exit codes: 0, 3, 1.

Commands¶

`huitzo pack new`¶

Scaffold a new Intelligence Pack project.

huitzo pack new [OPTIONS] [NAME]

Arguments:

Argument	Required	Description
`NAME`	No	Pack name (prompts if not provided)

Options:

Option	Default	Description
`--template`	`basic`	Template to use (`basic`, `advanced`, `full`)
`--namespace`	(from name)	Pack namespace
`--author`	(from git)	Author name
`--python`	`3.11`	Minimum Python version

Examples:

# Interactive mode
huitzo pack new

# Quick start with name
huitzo pack new my-pack

# Full customization
huitzo pack new my-pack --template advanced --namespace mycompany --author "John Doe"

Generated Structure:

my-pack/
├── pyproject.toml
├── huitzo.yaml
├── README.md
├── src/
│   └── my_pack/
│       ├── __init__.py
│       └── commands/
│           ├── __init__.py
│           └── hello.py
└── tests/
    ├── __init__.py
    └── test_hello.py

`huitzo pack dev`¶

Start a development session for testing your pack. This starts a local proxy that forwards requests to Huitzo's cloud sandbox where your pack code executes.

Important: Requires authentication. Run huitzo login first.

huitzo pack dev [OPTIONS]

Options:

Option	Default	Description
`--port`	`8080`	Local proxy port
`--host`	`localhost`	Host to bind to
`--persist`	`false`	Keep sandbox alive after Ctrl+C
`--watch`	`true`	Auto-upload on file changes
`--log-level`	`debug`	Logging level
`--no-docs`	`false`	Disable local docs server
`--docs-port`	`8124`	Local docs server port

Examples:

# Start with defaults
huitzo pack dev

# Custom proxy port
huitzo pack dev --port 9000

# Keep sandbox alive for debugging
huitzo pack dev --persist

# Network accessible (for testing from other devices)
huitzo pack dev --host 0.0.0.0 --port 8080

# Without docs server (faster startup)
huitzo pack dev --no-docs

Output:

🔐 Authenticating... OK ([email protected])
📦 Packaging pack... 3 commands found
☁️  Uploading to sandbox... done
📚 Starting docs server... done

🚀 Development session started

   Proxy:       http://localhost:8080
   API docs:    http://localhost:8080/docs
   Huitzo docs: http://localhost:8124

   Commands:
   - POST /api/v1/commands/mypack/command-1
   - POST /api/v1/commands/mypack/command-2
   - POST /api/v1/commands/mypack/command-3

📊 Quota: 847/1000 executions this month
⌨️  Press Ctrl+C to stop

[12:34:56] Watching for file changes...
[12:35:01] POST mypack/command-1 → 200 OK (142ms)
[12:35:15] File changed: commands/example.py
[12:35:16] Re-uploading... done

How It Works:

CLI authenticates with Huitzo using your JWT token
Pack code is packaged and uploaded to a cloud sandbox
Local proxy starts on your machine (localhost:8080)
Docs server clones/updates from github.com/Huitzo-Inc/docs and starts (localhost:8124)
Requests to the proxy are forwarded to the sandbox
File changes trigger automatic re-upload

Local Docs Server:

The docs server provides: - Web UI: Browse docs at http://localhost:8124 - MCP endpoint: http://localhost:8124/mcp for AI agent integration - Always current: Pulls latest docs from official repo on startup

Endpoints Available (via proxy):

GET /health - Health check
GET /docs - OpenAPI documentation
GET /api/v1/commands - List commands
POST /api/v1/commands/{namespace}/{name} - Execute command

Rate Limits:

Metric	Limit	Notes
Executions	1000/month	Hard limit, resets monthly
Concurrent sessions	1	Soft limit (warns on second)
Storage per sandbox	100 MB	Per-session limit

Note: You don't need PostgreSQL, Redis, or any other infrastructure locally. The cloud sandbox provides isolated storage, mock LLM services, and the full execution environment.

`huitzo pack test`¶

Run tests for your pack.

huitzo pack test [OPTIONS] [TESTS]

Arguments:

Argument	Required	Description
`TESTS`	No	Specific tests to run (default: all)

Options:

Option	Default	Description
`--coverage`	`false`	Generate coverage report
`--verbose`	`false`	Verbose test output
`--parallel`	`false`	Run tests in parallel
`--filter`	-	Filter tests by name pattern

Examples:

# Run all tests
huitzo pack test

# Run with coverage
huitzo pack test --coverage

# Run specific test file
huitzo pack test tests/test_hello.py

# Filter by name
huitzo pack test --filter "test_greet"

Output:

Running tests for my-pack...

tests/test_hello.py::test_hello_basic PASSED
tests/test_hello.py::test_hello_with_name PASSED
tests/test_hello.py::test_hello_error PASSED

========================= 3 passed in 0.42s =========================

Execution Statistics Collected:
  hello-basic:    p50=0.01s  p95=0.02s  max=0.03s
  hello-with-name: p50=0.02s  p95=0.04s  max=0.05s

Note: Execution statistics are collected during testing to enable automatic queue assignment. See Pack Manifest - Queue Options.

`huitzo stats`¶

View execution statistics collected during development.

huitzo stats [OPTIONS]

Options:

Option	Default	Description
`--json`	`false`	Output as JSON
`--reset`	`false`	Clear collected statistics

Examples:

# View stats
huitzo stats

# JSON output for CI/CD
huitzo stats --json

# Clear statistics
huitzo stats --reset

Output:

Command Statistics (from 47 test runs):

COMMAND              P50      P95      MAX      AUTO-QUEUE
get-user            0.02s    0.05s    0.08s    fast
analyze-data        2.10s    4.50s    6.20s    medium
generate-report    12.30s   45.00s   62.00s   long

Statistics stored in: .huitzo/stats.json

`huitzo pack validate`¶

Validate pack structure and manifest.

huitzo pack validate [OPTIONS] [PATH]

Arguments:

Argument	Required	Default	Description
`PATH`	No	`.`	Path to pack directory

Options:

Option	Default	Description
`--strict`	`false`	Enable strict validation
`--fix`	`false`	Auto-fix common issues

Examples:

# Validate current directory
huitzo pack validate

# Validate specific path
huitzo pack validate ./my-pack

# Strict mode
huitzo pack validate --strict

# Auto-fix issues
huitzo pack validate --fix

Output:

Validating my-pack...

✅ pyproject.toml valid
✅ huitzo.yaml valid
✅ Entry points configured
✅ Commands discoverable (3 found)
⚠️  Warning: No README.md found

Validation: PASSED with 1 warning

`huitzo pack build`¶

Build a distributable pack package.

huitzo pack build [OPTIONS]

Options:

Option	Default	Description
`--output`	`./dist`	Output directory
`--format`	`wheel`	Output format (`wheel`, `tar.gz`, `both`)
`--sign`	`false`	Sign the package

Examples:

# Build wheel
huitzo pack build

# Build to specific directory
huitzo pack build --output ./packages

# Build signed package
huitzo pack build --sign

Output:

Building my-pack...

📊 Embedding execution statistics...
   get-user:        fast queue (p95: 0.05s)
   analyze-data:    medium queue (p95: 4.50s)
   generate-report: long queue (p95: 45.00s)

📦 Created: dist/my_pack-1.0.0-py3-none-any.whl
   Size: 12.4 KB
   SHA256: abc123...

Build completed successfully!

Note: Execution statistics collected during huitzo pack dev and huitzo pack test are embedded in the built package. These statistics are used by the platform for automatic queue assignment. Run tests before building to ensure accurate statistics.

Note: pyproject.toml is automatically regenerated from huitzo.yaml before building if it is out of date.

`huitzo pack sync`¶

Regenerate pyproject.toml from huitzo.yaml.

huitzo pack sync [OPTIONS]

Options:

Option	Default	Description
`--path`	`.`	Path to pack root directory

Examples:

# Sync pyproject.toml from huitzo.yaml
huitzo pack sync

# Sync a pack in another directory
huitzo pack sync --path ./my-pack

Output:

Regenerated pyproject.toml

pyproject.toml is auto-generated from huitzo.yaml on huitzo pack build and huitzo pack dev. Use huitzo pack sync to regenerate it manually after editing huitzo.yaml.

`huitzo pack publish`¶

Publish pack to a registry.

huitzo pack publish [OPTIONS] [PACKAGE]

Arguments:

Argument	Required	Description
`PACKAGE`	No	Package file (default: latest build)

Options:

Option	Default	Description
`--registry`	`https://registry.huitzo.com`	Target registry
`--token`	(from config)	Authentication token
`--dry-run`	`false`	Simulate without publishing

Examples:

# Publish latest build
huitzo pack publish

# Publish specific package
huitzo pack publish ./dist/my_pack-1.0.0-py3-none-any.whl

# Dry run
huitzo pack publish --dry-run

Output:

Publishing [email protected]...

🔐 Authenticating with registry.huitzo.com
📤 Uploading my_pack-1.0.0-py3-none-any.whl (12.4 KB)
✅ Published successfully!

View at: https://registry.huitzo.com/packs/my-pack

`huitzo install`¶

Install a pack from registry or file.

huitzo install [OPTIONS] <PACK>

Arguments:

Argument	Required	Description
`PACK`	Yes	Pack name or file path

Options:

Option	Default	Description
`--version`	`latest`	Version to install
`--force`	`false`	Force reinstall
`--no-deps`	`false`	Skip dependencies

Examples:

# Install from registry
huitzo install financial-analysis

# Install specific version
huitzo install financial-analysis --version 2.0.0

# Install from file
huitzo install ./my_pack-1.0.0-py3-none-any.whl

# Force reinstall
huitzo install financial-analysis --force

Output:

Installing [email protected]...

📥 Downloading from registry.huitzo.com
🔐 Verifying signature
📦 Installing dependencies
✅ Installed successfully!

Commands available:
  - financial.analyze
  - financial.report
  - financial.compare

`huitzo uninstall`¶

Remove an installed pack. Deletes the pack and all its versions, commands, and access grants from the registry. Requires developer mode.

huitzo uninstall <PACK> [OPTIONS]

Arguments:

Argument	Required	Description
`PACK`	Yes	Pack name to uninstall

Options:

Flag	Description
`--force`	Skip confirmation prompt
`--output json`	Machine-readable JSON output

Examples:

# Interactive (prompts for confirmation)
huitzo uninstall financial-analysis

# Non-interactive (CI/automation)
huitzo uninstall financial-analysis --force --output json

Output:

Uninstalling financial-analysis...

✅ Removed [email protected]

Errors:

Error	Cause
"Developer mode required"	User account is not in developer mode
"Pack not found"	No pack with that name owned by the current tenant
"Only pack owner can delete packs"	Pack belongs to a different tenant

`huitzo list`¶

List installed packs.

huitzo list [OPTIONS]

Options:

Option	Default	Description
`--json`	`false`	Output as JSON
`--commands`	`false`	Show commands for each pack

Examples:

# List packs
huitzo list

# With commands
huitzo list --commands

# JSON output
huitzo list --json

Output:

Installed Packs:

PACK                    VERSION    COMMANDS
financial-analysis      2.0.0      3
notes                   1.2.0      4
weather                 1.0.0      2

`huitzo run`¶

Execute a command directly from CLI.

huitzo run <COMMAND> [ARGS...]

Arguments:

Argument	Required	Description
`COMMAND`	Yes	Command in `namespace.name` format
`ARGS`	No	Command arguments as `--key=value`

Options:

Option	Default	Description
`--json`	`false`	Output as JSON
`--raw`	`false`	Raw output (no formatting)
`--async`	`false`	Run asynchronously (returns task ID)

Examples:

# Run command
huitzo run notes.save --title="My Note" --content="Hello world"

# JSON output
huitzo run financial.analyze --symbol=AAPL --json

# Async execution
huitzo run reports.generate --format=pdf --async

Output:

Executing notes.save...

✅ Note saved successfully

{
  "id": "note_abc123",
  "title": "My Note",
  "created_at": "2025-01-22T10:30:00Z"
}

`huitzo login`¶

Authenticate with Huitzo services. Required before using huitzo pack dev or publishing packs.

huitzo login [OPTIONS]

Options:

Option	Default	Description
`--token`	-	Use API token directly
`--browser`	`true`	Open browser for OAuth login
`--config`	-	Use config file for enterprise auth

Examples:

# Browser login (default, opens browser for OAuth)
huitzo login

# API token login
huitzo login --token sk_xxxxx

# Enterprise/self-hosted login (uses .huitzo.yaml config)
huitzo login --config .huitzo.yaml

Output:

🔐 Opening browser for authentication...
✅ Logged in as [email protected]

   Organization: Acme Corp (@acme)
   Quota: 847/1000 executions this month

   Run 'huitzo pack dev' to start developing!

Self-Hosted Authentication:

For enterprise/self-hosted Huitzo instances, configure authentication in .huitzo.yaml:

# .huitzo.yaml
api_url: https://huitzo.acme-internal.com
auth:
  type: oidc           # or: api_key, saml
  issuer: https://auth.acme.com

Then login with:

huitzo login --config .huitzo.yaml

`huitzo logout`¶

Log out from Huitzo services.

huitzo logout

`huitzo status`¶

Display comprehensive environment status including authentication, server connectivity, codebase validity, and active dev sessions.

huitzo status [OPTIONS]

Options:

Option	Default	Description
`--json`	`false`	Output as JSON

Examples:

# Show full status
huitzo status

# Machine-readable output
huitzo status --json

Output sections:

Section	Description
Identity	Email, role, subscription tier, organization
Server	API URL, reachability, server version
Codebase	Whether current directory is a valid Intelligence Pack
Dev Sessions	Active development sessions (if authenticated)
Quick Reference	Common commands for daily use

Output (authenticated):

╭─ Identity ──────────────────────────────╮
│ Email   [email protected]                    │
│ Role    developer                       │
│ Tier    developer_preview               │
│ Org     acme                            │
╰─────────────────────────────────────────╯
╭─ Server ────────────────────────────────╮
│ API URL   https://huitzo.ai             │
│ Status    healthy                        │
│ Version   0.3.0                          │
╰─────────────────────────────────────────╯

Output (not authenticated):

╭─ Identity ──────────────────────────────╮
│ Not authenticated                        │
│ Run: huitzo login                        │
╰─────────────────────────────────────────╯

`huitzo config`¶

Manage CLI configuration.

huitzo config <SUBCOMMAND> [OPTIONS]

Subcommands:

Subcommand	Description
`get <KEY>`	Get config value
`set <KEY> <VALUE>`	Set config value
`list`	List all config
`path`	Show config file path

Examples:

# Get value
huitzo config get registry.url

# Set value
huitzo config set registry.url https://custom-registry.com

# List all
huitzo config list

# Show path
huitzo config path

`huitzo secrets`¶

Manage user secrets for packs. User secrets are per-user API keys that packs require to access external services.

huitzo secrets <SUBCOMMAND> [OPTIONS]

Subcommands:

Subcommand	Description
`set <PACK> <NAME> <VALUE>`	Set a secret for a pack
`list <PACK>`	List secrets for a pack
`remove <PACK> <NAME>`	Remove a secret
`show <PACK>`	Show secret metadata (not values)

Examples:

# Set a secret
huitzo secrets set @acme/financial-sync PLAID_CLIENT_ID "your_client_id"

# List secrets (shows names, not values)
huitzo secrets list @acme/financial-sync

# Remove a secret
huitzo secrets remove @acme/financial-sync PREMIUM_DATA_KEY

# Show secret metadata
huitzo secrets show @acme/financial-sync

Output:

Secrets for @acme/financial-sync:

NAME                STATUS      REQUIRED
PLAID_CLIENT_ID     ✅ Set      Yes
PLAID_SECRET        ✅ Set      Yes
PREMIUM_DATA_KEY    ⚪ Not set  No

Note: Secret values are never displayed. For security, secrets can only be set and removed, not read back.

`huitzo mcp`¶

Manage and interact with MCP (Model Context Protocol) servers configured in your pack.

huitzo mcp <SUBCOMMAND> [OPTIONS]

Subcommands:

Subcommand	Description
`list-servers`	List configured MCP servers
`list-tools <SERVER>`	List tools from an MCP server
`call <SERVER> <TOOL> [ARGS]`	Execute an MCP tool directly
`test <SERVER>`	Test connectivity to an MCP server

`huitzo mcp list-servers`¶

List all MCP servers configured in the current pack's manifest.

huitzo mcp list-servers [OPTIONS]

Options:

Option	Default	Description
`--json`	`false`	Output as JSON

Example:

huitzo mcp list-servers

Output:

MCP Servers (from huitzo.yaml):

NAME          TYPE     STATUS
github        stdio    ✅ Available
postgres      stdio    ✅ Available
slack         http     ✅ Available

`huitzo mcp list-tools`¶

List available tools from an MCP server.

huitzo mcp list-tools <SERVER> [OPTIONS]

Arguments:

Argument	Required	Description
`SERVER`	Yes	Name of the MCP server

Options:

Option	Default	Description
`--tool`	-	Filter to specific tool
`--schema`	`false`	Show JSON schema for tools
`--json`	`false`	Output as JSON

Examples:

# List all tools from GitHub server
huitzo mcp list-tools github

# Get schema for a specific tool
huitzo mcp list-tools github --tool create_issue --schema

# JSON output
huitzo mcp list-tools github --json

Output:

Tools from github:

TOOL                    DESCRIPTION
create_issue            Create a new GitHub issue
list_issues             List issues in a repository
get_issue               Get details of a specific issue
add_labels              Add labels to an issue
create_pull_request     Create a new pull request
list_repositories       List repositories for a user/org
...

Found 15 tools. Use --tool <name> --schema for details.

Schema Output:

huitzo mcp list-tools github --tool create_issue --schema

Tool: create_issue
Description: Create a new GitHub issue

Schema:
{
  "type": "object",
  "properties": {
    "owner": {"type": "string", "description": "Repository owner"},
    "repo": {"type": "string", "description": "Repository name"},
    "title": {"type": "string", "description": "Issue title"},
    "body": {"type": "string", "description": "Issue body"}
  },
  "required": ["owner", "repo", "title"]
}

`huitzo mcp call`¶

Execute an MCP tool directly from the CLI.

huitzo mcp call <SERVER> <TOOL> [ARGS]

Arguments:

Argument	Required	Description
`SERVER`	Yes	Name of the MCP server
`TOOL`	Yes	Name of the tool to execute
`ARGS`	No	Tool arguments as JSON string

Options:

Option	Default	Description
`--timeout`	`30`	Timeout in seconds
`--json`	`false`	Output raw JSON result

Examples:

# Call with JSON arguments
huitzo mcp call github create_issue '{"owner": "acme", "repo": "test", "title": "Test issue"}'

# Call with timeout
huitzo mcp call postgres query '{"sql": "SELECT * FROM users"}' --timeout 60

# Get raw JSON output
huitzo mcp call github list_issues '{"owner": "acme", "repo": "test"}' --json

Output:

Calling github.create_issue...

✅ Tool executed successfully

Result:
{
  "number": 42,
  "title": "Test issue",
  "html_url": "https://github.com/acme/test/issues/42",
  "state": "open"
}

`huitzo mcp test`¶

Test connectivity and authentication to an MCP server.

huitzo mcp test <SERVER> [OPTIONS]

Arguments:

Argument	Required	Description
`SERVER`	Yes	Name of the MCP server

Options:

Option	Default	Description
`--verbose`	`false`	Show detailed connection info

Examples:

# Basic connectivity test
huitzo mcp test github

# Verbose output
huitzo mcp test github --verbose

Output:

Testing connection to github...

✅ Connection successful
✅ Authentication valid
✅ Tools discovered: 15

Server: github
Type: stdio
Command: uvx mcp-server-github
Status: Ready

Verbose Output:

Testing connection to github...

[DEBUG] Spawning subprocess: uvx mcp-server-github
[DEBUG] Environment: GITHUB_TOKEN=****** (set)
[DEBUG] Sending initialize request...
[DEBUG] Received initialize response
[DEBUG] Sending tools/list request...
[DEBUG] Received 15 tools

✅ Connection successful
✅ Authentication valid
✅ Tools discovered: 15

Server Details:
  Name: github
  Type: stdio
  Command: ["uvx", "mcp-server-github"]
  Protocol Version: 2024-11-05
  Tools: create_issue, list_issues, get_issue, ...

Sandbox Commands¶

Commands for managing the local execution sandbox. The sandbox provides an isolated environment for running pack commands during development and agent-driven workflows.

`huitzo sandbox start`¶

Start a local sandbox environment.

huitzo sandbox start [OPTIONS]

Options:

Option	Default	Description
`--background`	`false`	Start in background mode (non-blocking)
`--timeout`	`3600`	Auto-stop after N seconds of inactivity

Examples:

# pseudocode — start sandbox interactively
huitzo sandbox start

# pseudocode — start in background for agent use
huitzo sandbox start --background --output json

`huitzo sandbox stop`¶

Stop the running sandbox and release resources.

huitzo sandbox stop [OPTIONS]

Examples:

# pseudocode — stop the sandbox
huitzo sandbox stop --output json

`huitzo sandbox status`¶

Check the current state of the sandbox.

huitzo sandbox status [OPTIONS]

Examples:

# pseudocode — query sandbox state
huitzo sandbox status --output json

# returns status, sandbox_id, uptime

Pack Execution Commands¶

Commands for executing pack commands and inspecting command metadata. These are typically used after starting a sandbox.

`huitzo pack exec`¶

Execute a specific pack command and return its result.

huitzo pack exec <NAMESPACE/COMMAND> [OPTIONS]

Arguments:

Argument	Required	Description
`NAMESPACE/COMMAND`	Yes	Fully qualified command identifier

Options:

Option	Default	Description
`--arg`	-	Command argument as `key=value` (repeatable)
`--timeout`	`60`	Execution timeout in seconds

Examples:

# pseudocode — execute a command with arguments
huitzo pack exec mypack/analyze --arg input="some data" --output json

`huitzo pack list-commands`¶

List all commands exposed by the current pack.

huitzo pack list-commands [OPTIONS]

Examples:

# pseudocode — discover available commands
huitzo pack list-commands --output json

`huitzo pack describe`¶

Show detailed metadata for a specific command, including its argument schema, timeout, and description.

huitzo pack describe <NAMESPACE/COMMAND> [OPTIONS]

Arguments:

Argument	Required	Description
`NAMESPACE/COMMAND`	Yes	Fully qualified command identifier

Examples:

# pseudocode — inspect command metadata
huitzo pack describe mypack/analyze --output json

Dashboard Commands¶

Commands for developing, building, and publishing Dashboards. Dashboards are micro-frontend applications that run inside Huitzo Hub and consume Intelligence Pack commands via the Dashboard SDK.

Workflow guide: See Dashboard CLI Guide for an end-to-end walkthrough with detailed template specification and troubleshooting.

`huitzo dashboard new`¶

Scaffold a new Dashboard project. Generates a React + TypeScript project configured as a micro-frontend with Vite library mode.

huitzo dashboard new [OPTIONS] [NAME]

Arguments:

Argument	Required	Description
`NAME`	No	Dashboard name (prompts if not provided)

Options:

Option	Default	Description
`--template`	`basic`	Template variant (`basic`, `tailwind`, `full`)
`--namespace`	(derived from name)	Dashboard namespace
`--author`	(from git config)	Author name

Examples:

# Interactive mode
huitzo dashboard new

# Quick start
huitzo dashboard new claims-dashboard

# With Tailwind template
huitzo dashboard new analytics --template tailwind

Generated Structure:

claims-dashboard/
├── huitzo-dashboard.yaml       # Dashboard manifest
├── package.json                # react, @huitzo/dashboard-sdk, @huitzo/dashboard-sdk-react
├── vite.config.ts              # Vite library mode — outputs dist/main.js
├── tsconfig.json
├── index.html                  # Dev-only — loads src/dev.tsx
├── src/
│   ├── main.tsx                # Production entry — exports mount() and unmount()
│   ├── dev.tsx                 # Dev-only — calls mount() with mock HuitzoContext
│   ├── App.tsx                 # Root component
│   ├── App.module.css          # CSS Modules (scoped styles)
│   └── components/
│       └── ErrorBoundary.tsx   # Catches React tree errors
└── .gitignore

See Dashboard CLI Guide — Step 1 for detailed file-by-file specification of the template.

`huitzo dashboard dev`¶

Start a dashboard development server with hot reload and API proxy. Uses the dev harness (src/dev.tsx) to simulate Hub by calling mount() with a mock context.

huitzo dashboard dev [OPTIONS]

Options:

Option	Default	Description
`--port`	`3000`	Development server port
`--api-url`	(from config)	Huitzo API URL for proxy
`--open`	`true`	Open browser on start

Examples:

# Start with defaults
huitzo dashboard dev

# Custom port
huitzo dashboard dev --port 5173

# Connect to local backend
huitzo dashboard dev --api-url http://localhost:8000

Output:

# pseudocode — example dev server output

Dashboard development server started

   Local:    http://localhost:3000
   Network:  http://192.168.1.100:3000

   API Proxy: http://localhost:8080 → /api/*

   Pack Dependencies:
   @acme/claims-processor (v0.1.0)
   @huitzo/analytics (v1.0.0)

Press Ctrl+C to stop

See Dashboard CLI Guide — Step 2 for dev mode details and how it differs from Hub mode.

`huitzo dashboard validate`¶

Validate dashboard manifest and build output without publishing.

huitzo dashboard validate [OPTIONS]

Examples:

# Validate current directory
huitzo dashboard validate

Output:

# pseudocode — example validation output

huitzo-dashboard.yaml found
dashboard.name: "claims-dashboard" (valid kebab-case)
dashboard.version: "1.2.0" (valid semver)
dashboard.namespace: "claims" (valid)
dashboard.min_sdk_version: "1.0.0" (valid semver)
pack_dependencies: 2 declared, all valid
dist/main.js found (entry point)
Bundle exports: mount, unmount (valid module contract)
Bundle size: 1.2 MB (under 50 MB limit)

All checks passed.

Validation checks:

Check	Description
Required fields	`name`, `namespace`, `version`, `description` present
Name format	kebab-case, 3-50 characters
Version format	Valid semver
Entry point	`dist/main.js` exists, exports `mount` and `unmount`
Bundle size	Tarball ≤ 50 MB, ≤ 500 files
SDK version	`min_sdk_version` is valid semver

See Dashboard CLI Guide — Step 4 for the full validation workflow. Canonical validation rules are in Dashboard Publishing — Validation Rules.

`huitzo dashboard build`¶

Build dashboard for production deployment.

huitzo dashboard build [OPTIONS]

Options:

Option	Default	Description
`--output`	`./dist`	Output directory
`--minify`	`true`	Minify output
`--sourcemap`	`false`	Generate source maps

Examples:

# Production build
huitzo dashboard build

# With source maps (for debugging)
huitzo dashboard build --sourcemap

# Custom output directory
huitzo dashboard build --output ./build

Output:

# pseudocode — example build output

Building claims-dashboard for production...

Build complete!

   Output: ./dist
   Size:   245 KB (gzipped: 72 KB)

   Files:
   - dist/main.js    (self-contained ESM — React + SDK + app + CSS)

Ready to validate with 'huitzo dashboard validate'

Note: The build output is a single self-contained ESM module (dist/main.js). CSS is injected into the JS module — there is no separate CSS file. No index.html is produced in library mode. See Dashboard Publishing — Build Contract.

See Dashboard CLI Guide — Step 3 for details.

`huitzo dashboard publish`¶

Publish dashboard to Huitzo Hub.

Cloud-gated: Requires Huitzo Cloud authentication.

huitzo dashboard publish [OPTIONS]

Options:

Option	Default	Description
`--visibility`	(from manifest)	Visibility level
`--dry-run`	`false`	Simulate without publishing

Examples:

# Publish to Huitzo Hub
huitzo dashboard publish

# Dry run
huitzo dashboard publish --dry-run

# Override visibility
huitzo dashboard publish --visibility unlisted

Output:

# pseudocode — example publish output

Publishing [email protected]...

Authenticating with Hub
Uploading dashboard (148 KB)
Published successfully!

Hub URL:     https://hub.huitzo.com/d/claims-dashboard
Explore:     https://hub.huitzo.com/explore/dashboards/claims-dashboard

Visibility: organization

See Dashboard CLI Guide — Step 5 for the full publish workflow. Version management details in Dashboard Publishing — Version Management.

`huitzo dashboard grant`¶

Grant access to specific organizations (for private/organization dashboards).

Cloud-gated: Requires Huitzo Cloud authentication.

huitzo dashboard grant <DASHBOARD> <ORGANIZATION>

Arguments:

Argument	Required	Description
`DASHBOARD`	Yes	Dashboard name
`ORGANIZATION`	Yes	Organization scope (e.g., `@acme`)

Examples:

# Grant access to an organization
huitzo dashboard grant claims-dashboard @partner-org

Output:

# pseudocode — example grant output

Granted @partner-org access to claims-dashboard

Current access:
- @acme (owner)
- @partner-org (granted)

See Dashboard CLI Guide — Step 6 for the access control workflow.

`huitzo dashboard revoke`¶

Revoke an organization's access to a dashboard.

Cloud-gated: Requires Huitzo Cloud authentication.

huitzo dashboard revoke <DASHBOARD> <ORGANIZATION>

Arguments:

Argument	Required	Description
`DASHBOARD`	Yes	Dashboard name
`ORGANIZATION`	Yes	Organization scope (e.g., `@acme`)

Examples:

# Revoke access from an organization
huitzo dashboard revoke claims-dashboard @partner-org

Output:

# pseudocode — example revoke output

Revoked @partner-org access to claims-dashboard

Current access:
- @acme (owner)

`huitzo dashboard delete`¶

Delete a dashboard from the registry. Removes the dashboard and all its versions and access grants. Requires developer mode.

huitzo dashboard delete <DASHBOARD> [OPTIONS]

Arguments:

Argument	Required	Description
`DASHBOARD`	Yes	Dashboard name (slug) to delete

Options:

Flag	Description
`--force`, `-f`	Skip confirmation prompt
`--output json`	Machine-readable JSON output

Examples:

# Interactive (prompts for confirmation)
huitzo dashboard delete claims-dashboard

# Non-interactive (CI/automation)
huitzo dashboard delete claims-dashboard --force --output json

Output:

# pseudocode — example delete output (interactive)

This will permanently delete claims-dashboard and all its versions.
Are you sure? [y/N]: y
Deleting claims-dashboard...

Deleted claims-dashboard

// pseudocode — example delete output (--output json)
{
  "ok": true,
  "data": {
    "dashboard_id": "<uuid>",
    "name": "claims-dashboard",
    "status": "deleted"
  }
}

Errors:

Error	Cause
"Developer mode required"	User account is not in developer mode
"Dashboard '`<name>`' not found"	No dashboard with that slug accessible to the current tenant
"Delete failed: ..."	Backend returned an error (e.g., dashboard belongs to a different tenant)
"Invalid dashboard name"	Name is not in kebab-case format

`huitzo dashboard share`¶

Generate a shareable link for unlisted dashboards.

Cloud-gated: Requires Huitzo Cloud authentication.

huitzo dashboard share <DASHBOARD> [OPTIONS]

Arguments:

Argument	Required	Description
`DASHBOARD`	Yes	Dashboard name

Options:

Option	Default	Description
`--expires`	`never`	Link expiration (`1d`, `7d`, `30d`, `never`)

Examples:

# Get shareable link
huitzo dashboard share claims-dashboard

# With expiration
huitzo dashboard share claims-dashboard --expires 7d

Output:

# pseudocode — example share output

Shareable link for claims-dashboard:

   https://hub.huitzo.com/d/abc123xyz

   Visibility: unlisted
   Expires: Never

Anyone with this link can view and install the dashboard.

Cross-Platform Usage¶

The Huitzo CLI works consistently across platforms. Here are platform-specific notes:

Command Syntax¶

# Linux/macOS
huitzo run analytics.analyze --file="/path/to/data.csv"

# Windows PowerShell
huitzo run analytics.analyze --file="C:\Users\me\data.csv"

# Windows Command Prompt
huitzo run analytics.analyze --file="C:\Users\me\data.csv"

Path Handling¶

The CLI accepts both forward slashes and backslashes on Windows:

# Both work on Windows
huitzo run pack.command --file="C:\data\file.csv"
huitzo run pack.command --file="C:/data/file.csv"

Environment Variables¶

# Linux/macOS (bash/zsh)
export HUITZO_API_URL="http://localhost:8000"
export HUITZO_LOG_LEVEL="DEBUG"

# Windows PowerShell
$env:HUITZO_API_URL = "http://localhost:8000"
$env:HUITZO_LOG_LEVEL = "DEBUG"

# Windows Command Prompt
set HUITZO_API_URL=http://localhost:8000
set HUITZO_LOG_LEVEL=DEBUG

Shell Completion¶

# Bash (Linux/macOS)
huitzo --install-completion bash
source ~/.bashrc

# Zsh (macOS)
huitzo --install-completion zsh
source ~/.zshrc

# PowerShell (Windows)
huitzo --install-completion powershell
# Restart PowerShell

Configuration¶

Config File Location¶

# Linux/macOS
~/.config/huitzo/config.toml

# Windows
%APPDATA%\huitzo\config.toml
# Typically: C:\Users\<username>\AppData\Roaming\huitzo\config.toml

Config File Format¶

# ~/.config/huitzo/config.toml

[auth]
token = "sk_xxxxx"

[registry]
url = "https://registry.huitzo.com"
timeout = 60

[dev]
port = 8080
reload = true
log_level = "debug"

[build]
output_dir = "./dist"
sign_packages = false

Environment Variables¶

Environment variables override config file:

Variable	Description
`HUITZO_TOKEN`	Authentication token
`HUITZO_REGISTRY_URL`	Registry URL
`HUITZO_CONFIG`	Config file path
`HUITZO_LOG_LEVEL`	Log level

Exit Codes¶

Code	Name	Meaning
0	OK	Command succeeded
1	General Error	Unclassified failure
2	Auth Error	Authentication failed or token expired
3	Validation Error	Input or manifest validation failed
4	Network Error	Could not reach the Huitzo API or registry
5	Server Error	Server returned a 5xx response
10	Command Error	Pack command execution failed
130	Interrupt	Process received SIGINT (Ctrl+C)

See Agent Integration for how agents should use exit codes for control flow.

Troubleshooting¶

Command Not Found¶

# Check installation
which huitzo

# Reinstall
pip uninstall huitzo-cli
pip install huitzo-cli

Authentication Issues¶

# Clear credentials
huitzo logout

# Re-authenticate
huitzo login

Outdated Dependencies¶

huitzo pack dev automatically checks if huitzo and huitzo-sdk have newer versions available on PyPI. This check runs in the background during startup and will not block or slow down your workflow.

Behavior: - Checks once per day (cached for 24 hours in the huitzo config directory, typically ~/.config/huitzo/update_check.json on Linux/macOS) - Only warns — never blocks startup - Silently skipped if offline or PyPI is unreachable

Disabling the check:

# CLI flag
huitzo pack dev --skip-update-check

# Environment variable (useful for CI)
# Accepted values: 1, true, yes (case-insensitive)
export HUITZO_SKIP_UPDATE_CHECK=1

Example output:

Warning: huitzo-sdk 0.0.0 installed, 0.0.2 available — run: pip install --upgrade huitzo-sdk

Dev Server Won't Start¶

# Check port availability
lsof -i :8080

# Use different port
huitzo pack dev --port 9000

Intelligence Projects — Optional scaffolding for fullstack Pack + Dashboard apps
Project Authoring — Workflow after huitzo project init
CLI Overview — Installation, design philosophy, and command groups
Dashboard CLI Guide — End-to-end dashboard development workflow
SDK Overview — Building Intelligence Packs
Pack Manifest — huitzo.yaml reference
Dashboard Framework Overview — Dashboard concepts and Hub integration
Dashboard Loading Architecture — How Hub loads and renders dashboards
Dashboard Publishing — Build contract, validation rules, version management
Dashboard Manifest — huitzo-dashboard.yaml reference
Dashboard SDK Reference — @huitzo/dashboard-sdk API
Secrets Management — User secrets
API Reference — REST API documentation

Huitzo CLI Reference¶

Installation¶

Global Options¶

Project Commands¶

huitzo project init¶

huitzo project add-pack¶

huitzo project add-dashboard¶

Commands¶

huitzo pack new¶

huitzo pack dev¶

huitzo pack test¶

huitzo stats¶

huitzo pack validate¶

huitzo pack build¶

huitzo pack sync¶

huitzo pack publish¶

huitzo install¶

huitzo uninstall¶

huitzo list¶

huitzo run¶

huitzo login¶

huitzo logout¶

huitzo status¶

huitzo config¶

huitzo secrets¶

huitzo mcp¶

huitzo mcp list-servers¶

huitzo mcp list-tools¶

huitzo mcp call¶

huitzo mcp test¶

Sandbox Commands¶

huitzo sandbox start¶

huitzo sandbox stop¶

huitzo sandbox status¶

Pack Execution Commands¶

huitzo pack exec¶

huitzo pack list-commands¶

huitzo pack describe¶

Dashboard Commands¶

huitzo dashboard new¶

huitzo dashboard dev¶

huitzo dashboard validate¶

huitzo dashboard build¶

huitzo dashboard publish¶

huitzo dashboard grant¶

huitzo dashboard revoke¶

huitzo dashboard delete¶

huitzo dashboard share¶

Cross-Platform Usage¶

Command Syntax¶

Path Handling¶

Environment Variables¶

Shell Completion¶

Configuration¶

Config File Location¶

Config File Format¶

Environment Variables¶

Exit Codes¶

Troubleshooting¶

Command Not Found¶

Authentication Issues¶

Outdated Dependencies¶

Dev Server Won't Start¶

Related Documentation¶

`huitzo project init`¶

`huitzo project add-pack`¶

`huitzo project add-dashboard`¶

`huitzo pack new`¶

`huitzo pack dev`¶

`huitzo pack test`¶

`huitzo stats`¶

`huitzo pack validate`¶

`huitzo pack build`¶

`huitzo pack sync`¶

`huitzo pack publish`¶

`huitzo install`¶

`huitzo uninstall`¶

`huitzo list`¶

`huitzo run`¶

`huitzo login`¶

`huitzo logout`¶

`huitzo status`¶

`huitzo config`¶

`huitzo secrets`¶

`huitzo mcp`¶

`huitzo mcp list-servers`¶

`huitzo mcp list-tools`¶

`huitzo mcp call`¶

`huitzo mcp test`¶

`huitzo sandbox start`¶

`huitzo sandbox stop`¶

`huitzo sandbox status`¶

`huitzo pack exec`¶

`huitzo pack list-commands`¶

`huitzo pack describe`¶

`huitzo dashboard new`¶

`huitzo dashboard dev`¶

`huitzo dashboard validate`¶

`huitzo dashboard build`¶

`huitzo dashboard publish`¶

`huitzo dashboard grant`¶

`huitzo dashboard revoke`¶

`huitzo dashboard delete`¶

`huitzo dashboard share`¶