Managing Plugins

HORUS provides CLI commands for managing plugins throughout their lifecycle.

Installing Plugins

Plugins are installed through the horus install --plugin command. They default to global installation since they extend the CLI tool itself.

# Install a plugin globally (default)
horus install --plugin horus-sim3d

# Install a specific version
horus install --plugin horus-sim3d -v 1.2.0

# Install locally to current project only
horus install --plugin horus-sim3d --local

What happens during installation:

  1. Downloads the package from the registry
  2. Detects plugin from the horus-* naming convention
  3. Registers the plugin binary in plugins.lock
  4. Creates symlinks in the bin directory
  5. Updates project configuration (for local installs)

Global vs Local Installation

AspectGlobalLocal
Location~/.horus/cache/.horus/packages/
ScopeAll projectsCurrent project only
Lock file~/.horus/plugins.lock.horus/plugins.lock
Default for pluginsYesNo (use --local)
Override behavior—Overrides global

Local plugins always take priority over global plugins with the same command name. This lets you pin a specific plugin version for a project without affecting other projects.

Listing Plugins

# List installed plugins
horus list

# List all plugins including disabled
horus list --all

Searching for Plugins

# Search for plugins by keyword
horus search camera

# Show all available plugins from registry
horus search

# Include local development plugins
horus search --local

# Show detailed info about a specific plugin
horus info horus-rplidar

Removing Plugins

# Remove a plugin
horus remove horus-sim3d

# Remove from global scope explicitly
horus remove horus-sim3d --global

Enabling and Disabling Plugins

You can temporarily disable a plugin without uninstalling it:

# Disable a plugin
horus disable sim3d

# Disable with a reason
horus disable sim3d --reason "Conflicts with sim2d"

# Re-enable it
horus enable sim3d

Disabled plugins remain installed but HORUS will not execute them.

Verifying Plugin Integrity

HORUS records SHA-256 checksums when plugins are installed. Verify that no binaries have been tampered with:

# Verify all plugins
horus verify

# Verify a specific plugin
horus verify sim3d

The plugins.lock File

Plugin registrations are stored in plugins.lock (JSON format). You typically don't need to edit this file directly:

{
  "schema_version": "1.0",
  "scope": "global",
  "horus_version": "0.1.9",
  "updated_at": "2025-10-15T10:30:00Z",
  "plugins": {
    "sim3d": {
      "package": "horus-sim3d",
      "version": "1.0.0",
      "source": { "type": "registry" },
      "binary": "/home/user/.horus/cache/horus-sim3d@1.0.0/bin/sim3d",
      "checksum": "sha256:abc123...",
      "installed_at": "2025-10-15T10:30:00Z",
      "installed_by": "0.1.9",
      "compatibility": {
        "horus_min": "0.1.0",
        "horus_max": "2.0.0"
      },
      "commands": [
        {
          "name": "sim3d",
          "description": "HORUS 3D robot simulator"
        }
      ]
    }
  },
  "disabled": {},
  "inherit_global": true
}

File locations:

  • Global: ~/.horus/plugins.lock
  • Project: .horus/plugins.lock

Using Plugins via horus install

The horus install command provides smart auto-detection. It recognizes plugins automatically:

# Auto-detects as a plugin and installs globally
horus install horus-sim3d

# Force install as plugin (if auto-detection fails)
horus install my-tool --plugin

Troubleshooting

Plugin Not Found

error: no such command: `mycommand`

Solutions:

# Check if plugin is installed
horus list

# Reinstall
horus install --plugin horus-mycommand

# Check if binary exists in PATH
which horus-mycommand

Checksum Mismatch

The binary was modified after installation. Reinstall:

horus install --plugin horus-mycommand

Plugin Binary Not Found

The package is registered but the binary is missing. Reinstall:

horus remove horus-mycommand
horus install --plugin horus-mycommand

Next Steps