Lab 3 — Publish and Share a Pack

labs publish visibility listing

Lab 3 — Publish and Share a Pack

Time: 30 minutes · Level: intermediate

Target audience

Developers who have a working pack (Labs 1-2) and want to publish one deliberately: with the right visibility, a clear publisher identity, and a version history you control.

Prerequisites

  • Lab 1 completed: developer mode enabled, a publishing namespace, and the CLI signed in.
  • A fresh pack for this lab (huitzo pack new lab-share --namespace your-namespace). Visibility is decided when a pack is first registered, so start from a pack you have not published yet.

Learning objectives

By the end of this lab you can:

  1. Explain the four visibility levels and pick the right one for a scenario.
  2. Add a listing: block so your pack carries a publisher identity and description.
  3. Publish a first version and confirm the visibility the platform recorded.
  4. Publish a second version and explain what changes and what does not.

1. Pick a visibility level

pack.visibility in huitzo.yaml controls who can discover and run the pack:

Level Who can find and use it
public Every tenant; searchable and browsable
unlisted Anyone with the pack link or ID; not searchable
organization Members of organizations holding an access grant
private Only the owning organization

The scaffold sets private. Use private or organization for this lab. public exposes the pack to every tenant, which you should do only deliberately, and unlisted packs do not appear in huitzo pack list even for their owner, which makes them awkward to verify and to re-publish with the current CLI. Read Visibility Levels before choosing public.

Important: the CLI sends visibility when it first registers the pack. A later huitzo pack publish uploads a new version but does not change the visibility recorded at registration. Set it correctly before your first publish.

2. Add listing metadata

Add an optional listing: block. Only publisher is required; everything else is presentation.

# pseudocode — huitzo.yaml fragment
listing:
  publisher:
    name: "Your Name or Company"
    contact_email: "[email protected]"
  short_description: "One sentence (max 160 characters)."
  long_description: "The full description shown on the listing page."

Free-text listing fields reject < and >. Field limits and the optional brand, links, and legal blocks are in the Listing Section.

3. Set the version and publish

The scaffold's version: 0.0.0 must be bumped before publishing (for example 0.1.0). Then:

# pseudocode
huitzo pack validate
huitzo pack publish

4. Check what the platform recorded

# pseudocode
huitzo pack list

Find your pack. The table shows its scope, name, visibility, and creation date. The visibility must match what you set in step 1. In the Hub terminal, packs shows the same pack with its visibility and command count.

5. Publish a second version

Change one command's behavior, bump version (for example to 0.1.1), and publish again. The CLI reports the pack as already registered and uploads the new version. Published versions are immutable, so republishing the same version number is rejected: bump it instead.

6. Verify who cannot see it

If you have a second account in a different organization, run packs in the Hub terminal as that account. A private or organization pack you published must not appear. If you only have one account, state in one sentence who could see your pack given its visibility, using the table in step 1.

Completion check

You are done when you can state, for your pack: (a) the visibility shown by huitzo pack list and that it matches the value you set before first publish, (b) that two versions were published, and (c) one observation from step 6 (or your one-sentence reasoning) about who cannot see it.

Follow-on resources