huitzo 0.1.8

Huitzo CLI for developers building Intelligence Packs

Huitzo CLI

A command-line tool for developers building Intelligence Packs on the Huitzo platform.

Status: Early development. Some features require Huitzo Cloud (not yet available).

Installation

Prerequisites

• Python 3.11 or later
• pip or uv package manager

Quick Start

# Install in editable mode for development
pip install -e .

# Verify installation
huitzo --version

Quick Start Guide

1. Initial Setup

# Login to Huitzo Cloud (when available)
huitzo login

# View your configuration
huitzo config list

2. Create Your First Pack

# Initialize a new Intelligence Pack
huitzo pack new my-pack
cd my-pack

# Validate the pack structure
huitzo pack validate

# Run tests
huitzo pack test

# Build the pack
huitzo pack build

3. Develop Your Pack

# Start development session (cloud required)
huitzo pack dev

# This will:
# - Upload your pack to a cloud sandbox
# - Watch for file changes and auto-reload
# - Provide a development dashboard at localhost:8080
# - Serve documentation at localhost:8124

4. Share Your Pack

# Publish to the Huitzo Registry (cloud required)
huitzo pack publish

# Grant access to other developers
huitzo dashboard grant --user [e-mail]

Commands

Authentication

# Login to Huitzo Cloud
huitzo login

# Logout
huitzo logout

Note: Huitzo Cloud is not yet available. Use --token <value> for testing.

Pack Development

# Initialize a new pack
huitzo pack new [NAME]

# Validate pack structure
huitzo pack validate

# Run pack tests
huitzo pack test [--coverage] [--verbose] [--filter PATTERN]

# Build a wheel for distribution
huitzo pack build [--output DIR] [--sign]

# Start development session
huitzo pack dev

# Note: `huitzo pack dev` requires Huitzo Cloud (not yet available)

Registry

# Publish pack to registry (cloud required)
huitzo pack publish

# Install a pack from registry
huitzo install <pack-name>

# Install from local file
huitzo install /path/to/pack.whl

# List installed packs
huitzo list

# Run a pack command (cloud required)
huitzo run <pack>:<command> [ARGS]

Configuration

# Get config value
huitzo config get <key>

# Set config value
huitzo config set <key> <value>

# List all config
huitzo config list

# Show config file path
huitzo config path

Secrets Management

# Set a secret (local storage only)
huitzo secrets set <name> <value>

# List secrets
huitzo secrets list

# Remove a secret
huitzo secrets remove <name>

# Show secret value
huitzo secrets show <name>

Dashboard

# Create a new dashboard project
huitzo dashboard new [NAME]

# Start development server
huitzo dashboard dev

# Build for production
huitzo dashboard build

# Publish to Huitzo Hub (cloud required)
huitzo dashboard publish

# Grant access
huitzo dashboard grant --user <email>

# Share dashboard
huitzo dashboard share --url

Configuration

Configuration is stored in ~/.config/huitzo/ (Linux/macOS) or %APPDATA%\huitzo\ (Windows).

Config Hierarchy (highest to lowest priority)

1. Environment variables: HUITZO_*
2. Command-line flags: --config <file>
3. User config: ~/.config/huitzo/config.yaml
4. Project config: ./huitzo.yaml
5. Defaults: built-in

Example Config

# ~/.config/huitzo/config.yaml
api_url: https://api.huitzo.dev
auth:
  token: <your-token>
  token_file: ~/.huitzo/token
dev:
  port: 8080
  verbose: false

Automation & Agent Integration

The CLI supports structured JSON output for AI agents and CI/CD pipelines. Pass --output json to any command to get a consistent envelope:

{"ok": true, "data": {...}}
{"ok": false, "error": {"type": "...", "message": "...", "code": N}}

Key features for automation:

• --output json for machine-readable output
• --non-interactive to suppress prompts (implied by JSON mode)
• HUITZO_TOKEN environment variable for non-interactive authentication
• huitzo sandbox start/stop/status for managing execution sandboxes
• huitzo pack exec, pack list-commands, pack describe for direct command execution
• Standardized exit codes (0=ok, 1=general, 2=auth, 3=validation, 4=network, 5=server, 10=command, 130=interrupt)

For the full specification, see the Agent Integration Guide.

Development

Setup Development Environment

# Clone the repository
git clone https://github.com/Huitzo-Inc/cli.git
cd cli

# Install with development dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Run type checking
mypy src/ --strict

# Run linting
ruff check .

# Format code
ruff format .

Project Structure

cli/
├── .github/workflows/     # CI/CD pipelines
├── src/huitzo_cli/        # Main package
│   ├── __init__.py
│   ├── main.py            # CLI entry point
│   ├── version.py         # Version management
│   ├── config.py          # Configuration management
│   ├── auth.py            # Authentication
│   ├── validator.py       # Pack validation
│   ├── commands/          # Command modules
│   │   ├── init.py        # Pack initialization
│   │   ├── auth.py        # Login/logout
│   │   ├── validate.py    # Validation command
│   │   ├── test.py        # Test runner
│   │   ├── build.py       # Build command
│   │   ├── dev.py         # Development session
│   │   ├── registry.py    # Registry operations
│   │   ├── config_cmd.py  # Config management
│   │   ├── secrets.py     # Secrets management
│   │   └── dashboard.py   # Dashboard operations
│   ├── templates/         # Scaffolding templates
│   ├── sandbox/           # Cloud sandbox integration
│   └── docs_server/       # Local docs server
├── tests/                 # Test suite
└── pyproject.toml         # Package configuration

Running Tests

# Run all tests
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=src/huitzo_cli --cov-report=html

# Run specific test file
pytest tests/test_main.py -v

# Run tests matching pattern
pytest tests/ -k "test_version" -v

Troubleshooting

Command Not Found

# Make sure the package is installed
pip list | grep huitzo-cli

# Reinstall
pip install -e .

# Check PATH
which huitzo

Permission Denied (config/secrets)

On Unix-like systems, configuration and secrets are stored with restricted permissions:

# Check permissions
ls -la ~/.config/huitzo/
ls -la ~/.huitzo/

# Should show 700 for directories, 600 for files

Cloud Features Not Available

Some commands require Huitzo Cloud, which is not yet available:

• huitzo login - Cloud authentication
• huitzo pack dev - Cloud sandbox
• huitzo pack publish - Cloud registry
• huitzo run - Cloud execution
• huitzo dashboard publish - Hub publishing

These commands will show "Coming soon" messages until the cloud platform is ready.

Cloud vs Local Features

Works Now (No Cloud Required)

• ✅ Pack scaffolding (huitzo pack new)
• ✅ Pack validation (huitzo pack validate)
• ✅ Running tests (huitzo pack test)
• ✅ Building wheels (huitzo pack build)
• ✅ Installing from local files (huitzo install <file>)
• ✅ Listing installed packs (huitzo list)
• ✅ Local configuration (huitzo config)
• ✅ Dashboard scaffolding (huitzo dashboard new/dev/build)

Coming Soon (Requires Huitzo Cloud)

• 🚧 Cloud authentication (huitzo login)
• 🚧 Cloud sandbox development (huitzo pack dev)
• 🚧 Cloud registry (huitzo pack publish)
• 🚧 Cloud execution (huitzo run)
• 🚧 Cloud secrets sync
• 🚧 Hub publishing (huitzo dashboard publish)

Contributing

Contributions are welcome! Please ensure:

1. All tests pass: pytest tests/
2. Code is formatted: ruff format .
3. Types are checked: mypy src/ --strict
4. Linting passes: ruff check .

License

Proprietary - Huitzo Inc.

Support

For issues or questions:

• GitHub Issues: https://github.com/Huitzo-Inc/cli/issues
• Documentation: https://docs.huitzo.dev/cli/
• Discord: https://discord.gg/huitzo

---

Note: This is an early-stage tool. APIs and commands may change. Huitzo Cloud features are coming soon.