Lab 1 — Your First Pack

labs first-pack cli hub

Lab 1 — Your First Pack

Time: 15 minutes · Level: beginner

Target audience

Developers new to Huitzo who want to see the full loop — CLI on your machine, a local dev session, a published pack visible in the Hub — once, end to end, before reading anything deeper.

Prerequisites

  • A Huitzo account and the CLI installed (Installation).
  • You are signed in: huitzo login completes without error.
  • Developer mode enabled on your account (publishing is refused otherwise): huitzo account developer-mode.
  • Your publishing namespace: a pack can only be published under your personal namespace (your tenant slug) or an organization you belong to. You will pass it to huitzo pack new --namespace.
  • Python knowledge at the level of writing an async function and a Pydantic model.

Learning objectives

By the end of this lab you can:

  1. Scaffold a pack with huitzo pack new and explain what huitzo.yaml is for.
  2. Run a command from a local dev session.
  3. Validate and publish a pack.
  4. Find your published pack from the Hub.

1. Scaffold the pack

# pseudocode — pick your own name; use your own publishing namespace
huitzo pack new lab-notes --namespace your-namespace
cd lab-notes

A pack name is 3-40 characters, starts with a lowercase letter, ends with a lowercase letter or digit, and uses only lowercase letters, digits, and hyphens in between (the full pack-name rules); the CLI rejects anything else with a validation error. huitzo.yaml is the single source of truth for the pack; pyproject.toml is generated from it. The scaffold sets version: 0.0.0 and visibility: private; you will bump the version before publishing.

2. Write one command

Open the generated example command under src/lab_notes/commands/ and replace its body with one command that greets a name and remembers the last greeting in per-user storage. The shape to follow is described in Your First Pack, Step 2: a Pydantic args model, an @command function taking (args, ctx), and ctx.storage for persistence.

Make sure the command is listed under commands: in huitzo.yaml with its entry_point, and that permissions and policy.allowed_actions include storage:read and storage:write. Schema v2 requires a policy: block; see Pack Manifest.

3. Run it in a dev session

# pseudocode — start the dev session
huitzo pack dev

huitzo pack dev requires you to be signed in, starts a local sandbox for your pack (HTTPS with a self-signed certificate on localhost), and prints an auth token variable and an example request. Platform services such as LLM and HTTP are stubbed unless you pass --local-keys, and storage is local to the session, so you need no database or Redis. Leave it running and, in a second terminal, call your command the way the session output shows: a POST to /commands/<name> with Authorization: Bearer $HUITZO_DEV_TOKEN (use curl -k for the self-signed certificate; GET /commands lists the exact names). The export HUITZO_DEV_TOKEN="****" line the session prints is deliberately masked — the CLI never writes token bytes to stdout, so they cannot leak into CI logs or terminal scrollback — so set the variable yourself in that second terminal: run huitzo config get --reveal auth.token, which prints auth.token = <token>, and copy that value into export HUITZO_DEV_TOKEN="<token>".

Checkpoint: the response contains the greeting you expect, and calling it a second time shows the value the first call stored.

4. Validate and publish

# pseudocode — stop the dev session first (Ctrl+C), and bump
# `pack.version` from 0.0.0 in huitzo.yaml (for example to 0.1.0)
huitzo pack validate
huitzo pack publish

validate must finish PASSED (warnings are fine). publish clean-builds from your current source and registers the pack under your namespace. If it fails with "Developer mode required" or a namespace mismatch, revisit the prerequisites. Published versions are immutable: if you need to change something later, bump version in huitzo.yaml and publish again.

5. Run the published command from the CLI

# pseudocode — use your own scope, pack, and command names
huitzo run @yourscope/lab-notes/greet --name Ada

6. Find it in the Hub

Sign in to the Hub, open the terminal, and run:

packs

Your pack is listed with its @scope/name, visibility, and command count. cd @yourscope/lab-notes sets it as the current pack context.

Completion check

You are done when both are true:

  • huitzo run @yourscope/lab-notes/greet ... prints a JSON result from the published pack.
  • packs in the Hub terminal lists @yourscope/lab-notes.

If the first fails, re-run huitzo pack validate and check that you are logged in (huitzo status). If the second fails, confirm you are signed in to the same account or organization the CLI published to.

Follow-on resources