azu plugin

Manage Azu CLI plugins to extend functionality with custom commands and generators.

Synopsis

azu plugin <operation> [arguments] [options]

Description

The plugin command provides functionality to list, install, uninstall, enable, disable, and inspect plugins for the Azu CLI. Plugins allow you to extend the CLI with custom commands, generators, and functionality specific to your workflow or organization.

Operations

azu plugin list

Display all installed plugins.

Synopsis

azu plugin list

Description

Lists all available plugins, including both built-in plugins that ship with Azu CLI and any external plugins you've installed.

Example Output

Installed plugins:

Built-in plugins:
  generator    - Code generation plugin
  database     - Database operations plugin
  development  - Development server plugin

External plugins:
  custom-auth  - Custom authentication plugin (v1.2.0)
  analytics    - Analytics integration plugin (v0.5.0)

Examples

# List all plugins
azu plugin list

---

azu plugin install

Install a plugin from a repository or local path.

Synopsis

azu plugin install <name> [options]

Description

Downloads and installs a plugin, making it available for use with the Azu CLI. Plugins can be installed from:

• Official Azu plugin registry

• GitHub repositories

• Local file paths

Arguments

Argument	Description
<name>	Plugin name or repository URL

Options

Option	Description
--source <url>	Plugin source URL
--version <version>	Specific version to install
--local <path>	Install from local directory
--global	Install globally (available to all projects)

Examples

# Install plugin from registry
azu plugin install custom-validator

# Install from GitHub
azu plugin install https://github.com/username/azu-plugin-name

# Install specific version
azu plugin install analytics --version 0.5.0

# Install from local directory
azu plugin install --local ~/my-plugins/custom-generator

# Install globally
azu plugin install monitoring --global

Plugin Structure

Plugins should follow this structure:

my-plugin/
├── shard.yml
├── src/
│   └── my_plugin/
│       ├── commands/
│       │   └── custom_command.cr
│       ├── generators/
│       │   └── custom_generator.cr
│       └── plugin.cr
└── README.md

Plugin Definition

# src/my_plugin/plugin.cr
require "topia/plugin"

module MyPlugin
  class Plugin < Topia::Plugin
    name "my-plugin"
    version "1.0.0"
    description "Custom plugin functionality"

    def setup
      register_command Commands::CustomCommand
      register_generator Generators::CustomGenerator
    end
  end
end

---

azu plugin uninstall

Remove an installed plugin.

Synopsis

azu plugin uninstall <name>

Description

Removes a plugin from your system, cleaning up all associated files and configuration.

Arguments

Argument	Description
<name>	Name of the plugin to uninstall

Examples

# Uninstall plugin
azu plugin uninstall analytics

# Uninstall with confirmation
azu plugin uninstall custom-auth --force

Safety

• Built-in plugins cannot be uninstalled

• Confirmation prompt shown before removal

• Backup created automatically

---

azu plugin enable

Enable a previously disabled plugin.

Synopsis

azu plugin enable <name>

Description

Activates a plugin that was previously disabled, making its commands and features available again.

Arguments

Argument	Description
<name>	Name of the plugin to enable

Examples

# Enable plugin
azu plugin enable analytics

# Enable multiple plugins
azu plugin enable plugin1 plugin2 plugin3

---

azu plugin disable

Temporarily disable a plugin without uninstalling it.

Synopsis

azu plugin disable <name>

Description

Deactivates a plugin while keeping it installed. Disabled plugins do not load their commands or run initialization code.

Arguments

Argument	Description
<name>	Name of the plugin to disable

Examples

# Disable plugin
azu plugin disable analytics

# Disable for troubleshooting
azu plugin disable problematic-plugin

Use Cases

• Troubleshooting plugin conflicts

• Temporarily removing functionality

• Testing without plugins

• Development and debugging

---

azu plugin info

Display detailed information about a plugin.

Synopsis

azu plugin info <name>

Description

Shows comprehensive information about a specific plugin, including version, description, status, dependencies, and provided commands.

Arguments

Argument	Description
<name>	Name of the plugin to inspect

Example Output

Plugin information for: analytics

Name: analytics
Version: 0.5.0
Status: enabled
Type: external
Author: Analytics Team
License: MIT

Description:
  Integrates application analytics with external tracking services.
  Provides commands for tracking events, users, and custom metrics.

Dependencies:
  - http_client >= 1.0.0
  - json >= 1.0.0

Commands:
  analytics:setup    - Configure analytics integration
  analytics:track    - Send tracking event
  analytics:report   - Generate analytics report

Generators:
  analytics:event    - Generate analytics event tracker

Installation Path:
  /usr/local/lib/azu/plugins/analytics

Repository:
  https://github.com/analytics-team/azu-plugin-analytics

Examples

# Show plugin information
azu plugin info analytics

# Check built-in plugin details
azu plugin info generator

---

Built-in Plugins

Azu CLI ships with several built-in plugins:

Generator Plugin

Name: generator Description: Code generation plugin for Azu CLI

Provides all code generation commands:

• azu generate model

• azu generate endpoint

• azu generate scaffold

• And more...

Database Plugin

Name: database Description: Database operations plugin for Azu CLI

Provides database management commands:

• azu db:create

• azu db:migrate

• azu db:rollback

• And more...

Development Plugin

Name: development Description: Development server plugin for Azu CLI

Provides development tools:

• azu serve

• azu test --watch

• Hot reloading functionality

---

Creating Custom Plugins

Plugin Template

# shard.yml
name: my-plugin
version: 1.0.0

dependencies:
  topia:
    github: azutoolkit/topia
  azu_cli:
    github: azutoolkit/azu_cli

# src/my_plugin.cr
require "topia/plugin"
require "./my_plugin/**"

module MyPlugin
  class Plugin < Topia::Plugin
    name "my-plugin"
    version "1.0.0"
    description "My custom plugin"
    author "Your Name"
    license "MIT"

    def setup
      # Register commands
      register_command Commands::MyCommand

      # Register generators
      register_generator Generators::MyGenerator

      # Run initialization code
      configure_plugin
    end

    private def configure_plugin
      # Plugin configuration
    end
  end
end

Custom Command Example

# src/my_plugin/commands/my_command.cr
require "azu_cli/commands/base"

module MyPlugin
  module Commands
    class MyCommand < AzuCLI::Commands::Base
      def initialize
        super("my:command", "Description of my command")
      end

      def execute : Result
        Logger.info("Executing my custom command")

        # Command implementation

        success("Command completed")
      end

      def show_help
        puts "Usage: azu my:command [options]"
        puts ""
        puts "Description:"
        puts "  My custom command implementation"
        puts ""
        puts "Options:"
        puts "  --option <value>    Custom option"
      end
    end
  end
end

Custom Generator Example

# src/my_plugin/generators/my_generator.cr
require "teeplate"

module MyPlugin
  module Generators
    class MyGenerator < Teeplate::FileTree
      directory "#{__DIR__}/templates"

      @name : String

      def initialize(@name)
      end

      def snake_case_name
        @name.underscore
      end

      def camel_case_name
        @name.camelcase
      end
    end
  end
end

---

Plugin Configuration

Global Configuration

Plugins can be configured globally in ~/.azu/config.yml:

plugins:
  enabled:
    - generator
    - database
    - development
    - my-plugin

  disabled:
    - experimental-plugin

  settings:
    my-plugin:
      option1: value1
      option2: value2

Project Configuration

Project-specific plugin settings in .azu/config.yml:

plugins:
  my-plugin:
    enabled: true
    options:
      project_specific: true
      custom_setting: value

---

Best Practices

1. Follow Naming Conventions

# Good plugin names
azu-plugin-analytics
azu-plugin-custom-auth
azu-plugin-deployment

# Bad plugin names
my_plugin
custom
tool

2. Provide Comprehensive Documentation

Include:

• README with installation instructions

• Command documentation

• Configuration examples

• Troubleshooting guide

3. Version Your Plugin

Use semantic versioning:

version "1.2.3"
#        │ │ └─ Patch: Bug fixes
#        │ └─── Minor: New features (backward compatible)
#        └───── Major: Breaking changes

4. Test Thoroughly

# spec/my_plugin/commands/my_command_spec.cr
require "../../spec_helper"

describe MyPlugin::Commands::MyCommand do
  it "executes successfully" do
    command = MyPlugin::Commands::MyCommand.new
    result = command.execute
    result.should be_successful
  end
end

5. Handle Dependencies Gracefully

def setup
  unless system_has_redis?
    Logger.warn("Redis not found - some features disabled")
    return
  end

  register_command Commands::RedisCommand
end

---

Troubleshooting

Plugin Not Loading

Check plugin is enabled:

azu plugin list

Enable if disabled:

azu plugin enable my-plugin

Command Not Found

Verify plugin provides the command:

azu plugin info my-plugin

Check plugin is properly registered:

# In plugin.cr
def setup
  register_command Commands::MyCommand  # Ensure this line exists
end

Version Conflicts

Check installed versions:

azu plugin info my-plugin

Update to compatible version:

azu plugin uninstall my-plugin
azu plugin install my-plugin --version 2.0.0

Plugin Installation Fails

Check dependencies:

# Verify Crystal version
crystal --version

# Check Azu CLI version
azu version

Install dependencies:

cd /path/to/plugin
shards install

---

Plugin Registry

Official Plugins

Visit the official plugin registry:

https://plugins.azutoolkit.org

Community Plugins

Browse community-contributed plugins:

# Search for plugins
azu plugin search <keyword>

# Show popular plugins
azu plugin popular

# Show recently updated
azu plugin recent

---

Environment Variables

Variable	Description	Default
AZU_PLUGINS_DIR	Plugin installation directory	~/.azu/plugins
AZU_DISABLE_PLUGINS	Comma-separated list of plugins to disable
AZU_PLUGIN_REGISTRY	Custom plugin registry URL	Official registry

---

Related Commands

• azu help - Show help including plugin commands

• azu version - Show version including plugin versions

See Also

• Plugin Development Guide

• Topia Plugin API

• Plugin Registry