Namespaces¶

Namespaces organize commands in Huitzo and prevent naming collisions. This document covers the scoped namespace model, navigation patterns, and reserved prefixes.

Namespace Format¶

Commands in Huitzo are identified using a scoped namespace format:

@{scope}/{pack-name}/{command}

Components¶

Examples¶

@acme/claims-processor/process-claim
@huitzo/core/hello
@mycompany/analytics/generate-report
@jsmith/demo/greet

Scope Types¶

Organization Scopes¶

Organizations own their namespace scope. All packs published by an organization are under their scope:

@acme/             # Acme Corp's scope
@acme/claims       # Acme's claims pack
@acme/billing      # Acme's billing pack

User Scopes¶

Individual developers can publish under their username:

@jsmith/           # John Smith's personal scope
@jsmith/tools      # John's personal tools pack

Reserved Scopes¶

The following scopes are reserved by Huitzo:

Attempting to publish to reserved scopes will fail:

$ huitzo pack publish --scope @huitzo
Error: Scope @huitzo is reserved for official Huitzo packs

Scope Ownership¶

Scopes are assigned to organizations when Developer Mode is enabled. The scope is derived from the organization's slug and provides exclusive namespace ownership.

Enforcement: Scope ownership is enforced at the API level. When creating a pack, the scope must match either the user's personal tenant slug or an organization they belong to. Arbitrary scopes are rejected with a 403 error.

Namespace States¶

When checking a namespace via GET /api/v1/namespaces/{namespace}/check, one of three states is returned:

How Scope Assignment Works¶

User enables Developer Mode
    ↓
Creates Organization (slug: "acme")
    ↓
Scope @acme is assigned
    ↓
All packs published as: @acme/{pack-name}

Scope Derivation Rules¶

The @scope is derived directly from the organization slug:

Slug Validation¶

Organization slugs (and thus scopes) must follow strict rules:

Valid slugs:

acme
my-company
startup-2024
a1b2c3
org123

Invalid slugs:

A           # too short
My-Company  # uppercase not allowed
-acme       # starts with hyphen
acme-       # ends with hyphen
huitzo      # reserved
system      # reserved
a           # too short

Scope Uniqueness¶

Cloud Example:

Organization "Acme Corp" claims @acme
    ↓
Another user tries to create org with slug "acme"
    ↓
Error: SLUG_TAKEN - "acme" is already in use

Self-Hosted Example:

Company A self-hosts Huitzo, creates @internal
Company B self-hosts Huitzo, creates @internal
    ↓
Both work – each instance is isolated

Reserved Scope List¶

These slugs cannot be used for organizations:

Transferring Scope Ownership¶

Scope ownership transfers with organization ownership:

Organization "Acme Corp" (@acme)
    ↓
Owner transfers org to new owner
    ↓
@acme scope transfers with it
    ↓
All @acme/* packs remain under new owner's control

Multiple Organizations¶

Users with Developer Mode can belong to multiple organizations:

Jane (Developer Mode):
├── @acme (owner)
├── @consulting-firm (admin)
└── @side-project (owner)

When publishing, Jane selects which org/scope to use:
$ huitzo pack publish --scope @side-project

Command Resolution¶

When running a command, the platform resolves it in this order:

1. Fully qualified – @acme/claims/process (exact match)
2. Current scope – If user is in @acme/claims, process resolves to @acme/claims/process
3. Installed packs – Search installed packs for the command name

Collision Handling¶

If multiple packs have the same command name, use the fully qualified format:

# Both packs have "analyze" command
@acme/analytics/analyze    # Acme's analyze
@datatools/stats/analyze   # DataTools analyze

WebCLI Navigation¶

The WebCLI terminal in the Dashboard Hub supports filesystem-like navigation through namespaces using cd:

Navigation Commands¶

Navigation Examples¶

# Start at root
~/> pwd
/

# Navigate to scope
~/> cd @acme
@acme/> pwd
@acme

# List packs in scope
@acme/> ls
claims-processor/
billing/
analytics/

# Navigate to pack
@acme/> cd claims-processor
@acme/claims-processor/> pwd
@acme/claims-processor

# List commands in pack
@acme/claims-processor/> ls
process-claim
validate-claim
generate-report

# Run command (short form, since we're in the pack)
@acme/claims-processor/> process-claim --file claim.xlsx

# Go back up
@acme/claims-processor/> cd ..
@acme/> cd ..
~/>

# Direct navigation
~/> cd @acme/claims-processor
@acme/claims-processor/>

Prompt Format¶

The WebCLI prompt shows current location:

~/>                          # Root
@acme/>                      # In scope @acme
@acme/claims-processor/>     # In pack claims-processor under @acme

Running Commands¶

Commands can be run from any location:

# From root - fully qualified
~/> @acme/claims/process-claim --file claim.xlsx

# From scope - pack/command
@acme/> claims/process-claim --file claim.xlsx

# From pack - command only
@acme/claims/> process-claim --file claim.xlsx

Visibility Modes¶

Packs have visibility settings that control who can discover and use them:

Unlisted Packs¶

Unlisted packs are not discoverable through search or browsing but can be accessed with a direct link or pack ID:

# huitzo.yaml
pack:
  name: "acme-claims-processor"
  namespace: "claims"
  visibility: "unlisted"

Sharing Unlisted Packs:

# Get shareable link
$ huitzo pack share
Pack ID: pack_a1b2c3d4e5f6
Direct URL: https://app.huitzo.com/packs/pack_a1b2c3d4e5f6

# Install via ID
$ huitzo pack install pack_a1b2c3d4e5f6

Use Cases: - Agency builds pack for specific client (Client A can use, Client B cannot) - Beta testing with select users before public release - Custom implementations for enterprise customers

Visibility Configuration¶

Set visibility in huitzo.yaml:

pack:
  name: "my-pack"
  namespace: "mypack"
  visibility: "unlisted"  # public | unlisted | organization | private

Or during publish:

huitzo pack publish --visibility unlisted

Access Grants¶

For organization visibility, explicit access grants are required:

# Grant access to another organization
$ huitzo pack grant @clientorg --pack claims-processor
Access granted: @clientorg can now use @acme/claims-processor

Best Practices¶

Naming Conventions¶

1. Scope names – Organization name or username (lowercase)
2. Pack names – Descriptive, kebab-case (claims-processor, not cp)
3. Command names – Action-oriented, kebab-case (process-claim, not pc)

Avoid Collisions¶

1. Use your organization scope for all packs
2. Choose specific, descriptive command names
3. Prefix commands with context: claims-process not just process

Navigation Efficiency¶

1. Use cd to set context, then run multiple commands
2. Use cd @scope/pack for one-shot navigation
3. Use pwd when lost
4. Tab completion works for scopes, packs, and commands

Related Documentation¶

• Pack Manifest – Visibility and namespace configuration
• Commands Reference – Command definition and naming
• CLI Reference – CLI navigation and commands