Plugin Management

Apito CLI provides a comprehensive plugin management system that allows you to create, deploy, update, and manage HashiCorp-based plugins with hot reload capabilities.

config - Manage CLI Configuration

Configure accounts, server URLs, cloud sync keys, and other CLI settings for plugin management.

Usage:

apito config <command> [options]

Commands:

• set <key> <value> - Set a configuration value
• set <url|key> <value> - Set account-specific configuration with interactive selection
• set -a <account> <url|key> <value> - Set account-specific configuration with account flag
• set account <account-name> <url|key> <value> - Set account-specific configuration
• get [key] - Get configuration value(s)
• init - Initialize configuration interactively
• reset - Reset configuration to defaults

Configuration Keys:

• timeout - Request timeout in seconds (default: 30)
• default_plugin - Default plugin for operations
• mode - CLI run mode (docker or manual)
• default_account - Default account for plugin operations

Account Configuration:

• url - Apito server URL for the account
• key - Cloud sync key for the account

Examples:

# Interactive configuration setup (creates accounts)
apito config init

# Interactive account selection for setting values
apito config set key abc123...        # Shows account selection menu
apito config set url https://api.apito.io  # Shows account selection menu

# Set account-specific values with -a flag (recommended)
apito config set -a production key abc123...
apito config set -a staging url https://staging-api.apito.io

# Set account-specific values (existing patterns still work)
apito config set account production url https://api.apito.io
apito config set production key abc123...

# Set default account
apito config set default_account production

# View all configuration including accounts
apito config get

# View specific setting
apito config get default_account

# View all accounts
apito config get account

# Reset all configuration
apito config reset

account - Manage Multiple Accounts

Manage multiple Apito accounts for different environments (production, staging, local, etc.).

Usage:

apito account <command> [options]

Commands:

• create <account-name> - Create a new account with interactive setup
• list - List all configured accounts
• select <account-name> - Set default account for plugin operations
• test <account-name> - Test account connection and credentials
• delete <account-name> - Delete an account configuration

Examples:

# Create a new account
apito account create production

# List all accounts
apito account list

# Test account connection
apito account test production

# Set default account
apito account select production

# Delete an account
apito account delete staging

plugin - Manage HashiCorp Plugins

Create, deploy, update, and manage HashiCorp-based plugins with hot reload capabilities.

⚠️ Confirmation Required: Sensitive operations (deploy, update, delete, stop, restart) require confirmation and will display detailed information about the operation.

Usage:

apito plugin <command> [options]

Commands:

• create - Create a new plugin scaffold
• build [directory] - Build plugin based on language configuration
• deploy [directory] - Deploy plugin to server ⚠️ Requires confirmation
• update <plugin-id> [directory] - Update existing plugin ⚠️ Requires confirmation
• list - List all plugins on server
• status <plugin-id> - Get plugin status
• delete <plugin-id> - Delete plugin from server ⚠️ Requires confirmation
• restart <plugin-id> - Restart plugin ⚠️ Requires confirmation
• stop <plugin-id> - Stop plugin ⚠️ Requires confirmation
• start <plugin-id> - Start plugin
• env - Show build environment information

Options:

• --account, -a - Specify account to use for plugin operations (optional, uses default if not specified)
• --dir, -d - Plugin directory (for deploy/update commands)

Features:

• Hot Reload: Deploy and update plugins without server restarts
• Process Isolation: HashiCorp go-plugin framework for fault tolerance
• Multi-language Support: Go, JavaScript, Python plugin development
• Secure Deployment: Cloud sync key authentication
• Real-time Status: Live plugin status monitoring and health checks
• Template Generation: Scaffold creation with best practices
• Confirmation System: Sensitive operations require explicit confirmation

Plugin Creation Workflow:

# 1. Configure CLI for plugin management
apito config init
# This creates your first account interactively

# 2. Create additional accounts for different environments (optional)
apito account create staging
apito config set account staging url https://staging-api.apito.io
apito config set account staging key staging-key-456

# 3. Set default account
apito account select production

# 4. Create new plugin scaffold
apito plugin create
# Follow prompts to select:
# - Plugin name (e.g., hc-my-awesome-plugin)
# - Language (Go, JavaScript, Python)
# - Plugin type (System, Project, Custom)

# 5. Develop your plugin
cd hc-my-awesome-plugin
# Edit main.go or main.js based on your language choice
# Modify config.yml with plugin metadata

# 6. Build plugin
apito plugin build

# 7. Deploy plugin to server (uses default account)
apito plugin deploy

# 8. Check plugin status
apito plugin status hc-my-awesome-plugin

Plugin Build System:

The build system automatically detects the plugin language from config.yml and provides appropriate build options:

Go Plugins:

# Build Go plugin with interactive options
apito plugin build
# Options:
# - System vs Docker build
# - Debug (with debug symbols)
# - Development (basic build, GOOS=linux)
# - Production (static binary, CGO_ENABLED=0)

JavaScript Plugins:

# Build JavaScript plugin
apito plugin build
# Automatically runs:
# - npm install (install dependencies)
# - node --check index.js (syntax validation)

Python Plugins:

# Build Python plugin
apito plugin build
# Automatically runs:
# - pip3 install -r requirements.txt (if exists)
# - python3 -m py_compile main.py (syntax validation)

Plugin Configuration (config.yml):

plugin:
  id: "hc-your-plugin-name"
  language: "go" # go, js, python
  title: "Your Plugin Title"
  icon: "🔌"
  description: "Plugin description"
  type: "system" # system, project, custom
  role: "custom"
  exported_variable: "NormalPlugin"
  enable: true
  debug: false
  version: "1.0.0"
  author: "Your Name"
  repository_url: "https://github.com/your/repo"
  branch: "main"
  binary_path: "hc-your-plugin-name"
  handshake_config:
    protocol_version: 1
    magic_cookie_key: "APITO_PLUGIN"
    magic_cookie_value: "apito_plugin_magic_cookie_v1"
  env_vars:
    - key: "PLUGIN_DEBUG_MODE"
      value: "false"

Plugin Types:

• System Plugins: Core functionality, authentication, storage drivers
• Project Plugins: Project-specific business logic and workflows
• Custom Plugins: User-defined functionality and integrations

Supported Languages:

• Go: Native HashiCorp go-plugin support with maximum performance
• JavaScript: Node.js-based plugins with npm ecosystem access
• Python: Python plugins with pip package management