Publishing & Registry

The HORUS Registry is the package ecosystem for robotics — drivers, algorithms, plugins, and tools shared across the community. This page covers the author/publisher workflow. For installing packages, see Package Management.

Full guide: The registry website has a comprehensive Publisher Guide with screenshots and detailed walkthroughs. This page is a quick reference.

Authentication

# Login with GitHub (opens browser)
horus auth login

# Check who you're logged in as
horus auth whoami

# Generate API key for CI/CD publishing
horus auth api-key --name github-actions --environment ci-cd

# Generate Ed25519 signing key for package signing
horus auth signing-key

# List and revoke API keys
horus auth keys list
horus auth keys revoke <key_id>

# Logout
horus auth logout

Publishing a Package

1. Prepare your package

Your horus.toml must have at minimum:

[package]
name = "my-lidar-driver"
version = "0.1.0"
description = "RPLiDAR A2 driver for HORUS"
license = "MIT"
package-type = "driver"
categories = ["lidar", "driver"]

2. Validate

horus publish --dry-run
# Validates: horus.toml, source files, builds, checks package size

3. Publish

horus publish

The registry validates the package, builds it, and makes it available for horus install and horus add.

Rules:

• Package names must be unique across the registry
• Once a version is published, that version number cannot be reused — bump the version for changes
• Version must follow semver: MAJOR.MINOR.PATCH

Version Management

Yanking (reversible)

Yanking hides a version from new installs but doesn't break existing users who already have it:

# Yank a broken version
horus yank my-lidar-driver@0.1.0 --reason "bug in scan parsing"

# Reverse a yank
horus unyank my-lidar-driver@0.1.0

Unpublishing (irreversible)

Permanently deletes a version. Use with caution — other packages may depend on it:

horus unpublish my-lidar-driver@0.1.0 --yes

Deprecating a Package

Mark an entire package as deprecated to discourage new installs:

# Deprecate with a migration message
horus deprecate my-lidar-driver -m "Use rplidar-driver-v2 instead"

# Remove deprecation
horus undeprecate my-lidar-driver

Ownership & Transfer

Packages can have multiple owners. Any owner can publish new versions and manage other owners.

# List current owners
horus owner list my-lidar-driver

# Add a co-owner
horus owner add my-lidar-driver --user teammate

# Remove an owner
horus owner remove my-lidar-driver --user former-teammate

# Transfer ownership to another user
horus owner transfer my-lidar-driver --target new-maintainer

# Accept a pending transfer
horus owner accept <transfer-id>

CI/CD Publishing

Automate publishing from GitHub Actions or GitLab CI:

# .github/workflows/publish.yml
name: Publish to HORUS Registry
on:
  push:
    tags: ['v*']

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install HORUS
        run: curl -fsSL https://raw.githubusercontent.com/softmata/horus/release/install.sh | bash
      - name: Publish
        run: horus publish
        env:
          HORUS_API_KEY: ${{ secrets.HORUS_API_KEY }}

Generate the API key:

horus auth api-key --name github-actions --environment ci-cd
# Save the key as a GitHub secret: HORUS_API_KEY

Developer Portal

The Developer Portal is a web dashboard for managing your published packages. After signing in with GitHub, you can:

• Edit metadata — description, categories, keywords, README
• Browse source files — syntax-highlighted file browser
• View download stats — charts showing trends over time
• Manage owners — add/remove co-owners, transfer ownership
• Yank/unyank versions — via web UI instead of CLI
• Deprecate packages — with a migration message
• Upload media — screenshots, GIFs, video embeds
• View build status — trigger verification, view logs
• Generate API keys — for CI/CD publishing
• SBOM viewer — software bill of materials
• License compatibility — check across dependency tree

Package Types

Set in horus.toml:

[package]
package-type = "driver"

Common Errors

See Also

• Package Management — Installing and managing packages
• Using Pre-Built Nodes — Compose systems from registry packages
• Configuration Reference — horus.toml format
• CLI Reference — All publish/auth/owner commands
• Registry Guide — Full publisher guide on the registry website