# 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

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

# Verify installation
huitzo --version
```

## Quick Start Guide

### 1. Initial Setup

```bash
# Login to Huitzo Cloud (when available)
huitzo login

# View your configuration
huitzo config list
```

### 2. Create Your First Pack

```bash
# 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

```bash
# 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

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

# Grant access to other developers
huitzo dashboard grant --user alice@example.com
```

## Commands

### Authentication

```bash
# Login to Huitzo Cloud
huitzo login

# Logout
huitzo logout
```

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

### Pack Development

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

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

## Development

### Setup Development Environment

```bash
# 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

```bash
# 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

```bash
# 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:

```bash
# 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.
