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

azu help - Show help including plugin commands
azu version - Show version including plugin versions

Synopsis

Description

Operations

azu plugin list

Synopsis

Description

Example Output

Examples

azu plugin install

Synopsis

Description

Arguments

Options

Examples

Plugin Structure

Plugin Definition

azu plugin uninstall

Synopsis

Description

Arguments

Examples

Safety

azu plugin enable

Synopsis

Description

Arguments

Examples

azu plugin disable

Synopsis

Description

Arguments

Examples

Use Cases

azu plugin info

Synopsis

Description

Arguments

Example Output

Examples

Built-in Plugins

Generator Plugin

Database Plugin

Development Plugin

Creating Custom Plugins

Plugin Template

Custom Command Example

Custom Generator Example

Plugin Configuration

Global Configuration

Project Configuration

Best Practices

1. Follow Naming Conventions

2. Provide Comprehensive Documentation

3. Version Your Plugin

4. Test Thoroughly

5. Handle Dependencies Gracefully

Troubleshooting

Plugin Not Loading

Command Not Found

Version Conflicts

Plugin Installation Fails

Plugin Registry

Official Plugins

Community Plugins

Environment Variables

Related Commands

See Also

`azu plugin list`

`azu plugin install`

`azu plugin uninstall`

`azu plugin enable`

`azu plugin disable`

`azu plugin info`