Plugins

HORUS supports CLI plugins — standalone binaries that add new subcommands to the horus command. When you run horus sim3d, HORUS discovers and executes the sim3d plugin binary, passing through all arguments.

How CLI Plugins Work

  1. Any package named horus-* with a binary is automatically a plugin
  2. Installing it registers the binary with the HORUS plugin system
  3. Running horus <command> checks plugins before showing "unknown command"
# Install a plugin
horus install --plugin horus-sim3d

# Use it as a native command
horus sim3d --robot kuka_iiwa

# List installed plugins
horus list

Plugin Resolution Order

PriorityLocationScope
1st.horus/plugins.lock (project)Local project only
2nd~/.config/horus/plugins.lock (global)All projects
3rd.horus/bin/horus-* (project)Local project only
4th~/.config/horus/bin/horus-* (global)All projects
5thPATH lookup for horus-* binariesSystem-wide

The global locations live in the platform config directory: $XDG_CONFIG_HOME/horus (defaulting to ~/.config/horus) on Linux, ~/Library/Application Support/horus on macOS, and %APPDATA%\horus on Windows.

Project plugins override global ones, so you can pin a specific version per project.

Project-scoped plugins (rows 1 and 3) are resolved first but are refused at execution time until you trust them on this machine — they live inside the checkout, so cloning a repository never grants its plugins the right to run. Run horus plugin trust <command> before using one; see Security below.

Security

Installed plugins are verified via SHA-256 checksums recorded at install time. Before execution, HORUS verifies the binary hasn't been modified:

# Verify all installed plugins
horus plugin verify

# Verify a single plugin
horus plugin verify sim3d

For project-local plugins, a checksum in .horus/plugins.lock is not proof of trust — that file ships inside the checkout, so the repository controls it. Such plugins must be trusted on this machine before they will execute:

# Trust a project-local plugin so it may execute
horus plugin trust mytool

# List plugins trusted on this machine
horus plugin trusted

# Revoke trust (the plugin refuses to execute afterwards)
horus plugin untrust mytool

Next Steps