aura plugins

Manage Go plugins.

Syntax

aura plugins list
aura plugins show <name|pack>
aura plugins add <source> [source...] [flags]
aura plugins update [name|pack...] [flags]
aura plugins remove <name|pack> [name|pack...]

Description

Plugins are user-defined Go modules that hook into the conversation lifecycle via the Yaegi interpreter. The aura plugins command manages the full lifecycle: listing, inspecting, installing from git or local paths, updating, and removing.

See Plugins for details on writing plugins.

Subcommands

Subcommand	Description
list	Show all plugins with status, capabilities, and source
show <name\|pack>	Full plugin details, or pack overview with member list
add <source> [source...]	Install plugins from git URLs or local paths
update [name\|pack...]	Pull latest from git origin (resolves to pack if applicable)
remove <name\|pack> [name\|pack...]	Remove standalone plugins or entire packs

Add Flags

Flag	Default	Description
--name	(derived)	Custom directory name for the plugin
--ref	(default branch)	Git ref to checkout (tag, branch, or commit)
--subpath		Subdirectory within the source to use as plugin root (repeatable)
--global	false	Install to ~/.aura/plugins/ instead of local
--no-vendor	false	Skip go mod tidy and go mod vendor after installing

Update Flags

Flag	Default	Description
--all	false	Update all git-sourced plugins
--no-vendor	false	Skip go mod tidy and go mod vendor after updating

Naming

The plugin name defaults to the last path segment of the source URL, stripped of the aura-plugin- prefix:

• github.com/user/aura-plugin-metrics → metrics/
• github.com/user/my-hooks → my-hooks/

When a single --subpath is provided without --name, the name is derived from the subpath’s last segment instead of the URL:

• --subpath plugins/injectors → injectors/

With multiple --subpath flags, the name falls back to URL-based derivation (the repo is cloned as a pack).

Override with --name (single source only — --name and --ref cannot be used with multiple sources).

Plugin Packs

A single repository can contain multiple plugins in subdirectories. Each subdirectory must have its own plugin.yaml, go.mod, and .go files:

github.com/user/aura-plugins/
  gotify/
    plugin.yaml
    go.mod
    main.go
  slack/
    plugin.yaml
    go.mod
    main.go

All plugins are discovered and installed together. Each plugin is loaded independently. Update and remove operate at the pack level — use disabled: true in plugin.yaml to skip individual plugins within a pack.

Authentication

For HTTPS repositories, authentication is tried in order:

1. No auth (public repos)
2. Environment tokens: GIT_USERNAME/GIT_PASSWORD, GITHUB_TOKEN, GITLAB_TOKEN, GIT_TOKEN
3. git credential fill

For SSH URLs:

1. SSH agent
2. SSH key files (~/.ssh/id_ed25519, id_rsa, id_ecdsa)

Examples

# List all plugins
aura plugins list

# Inspect a plugin
aura plugins show metrics

# Install from git (default branch)
aura plugins add https://github.com/user/aura-plugin-metrics

# Install a specific tag
aura plugins add https://github.com/user/aura-plugin-metrics --ref v0.2.0

# Install via SSH
aura plugins add git@github.com:user/aura-plugin-metrics.git

# Install with custom name
aura plugins add https://github.com/user/aura-plugin-metrics --name custom-name

# Install globally
aura plugins add https://github.com/user/aura-plugin-metrics --global

# Install from local path
aura plugins add ./path/to/my-plugin --name my-plugin

# Install a plugin pack (multiple plugins in one repo)
aura plugins add https://github.com/user/aura-plugins

# Install without vendoring dependencies
aura plugins add https://github.com/user/aura-plugin-metrics --no-vendor

# Update by plugin name (resolves to its pack)
aura plugins update gotify

# Update by pack name directly
aura plugins update tools

# Update all git-sourced plugins
aura plugins update --all

# Show a pack overview
aura plugins show tools

# Remove a standalone plugin
aura plugins remove my-standalone

# Remove an entire pack
aura plugins remove tools