Pets CLI

A command-line interface for managing OpenCode pets plugins. This tool allows you to validate plugins and display information about available pets listed in the local opencode.json file.

Installation

The CLI is included in the pets package. To build and use it:

# Build the CLI
npm run build-cli

# Use directly
./pets.sh <command> [options]

# Or use with node
node src/core/cli.js <command> [options]

Commands

validate

Validate plugins in current directory or pets directory.

Options:

• -a, --all - Validate all plugins in pets directory
• -p, --plugin <name> - Validate a specific plugin by name
• -d, --directory <path> - Specify pets directory (default: ./pets)

Examples:

# Validate current directory
pets validate

# Validate all plugins in ./pets
pets validate --all

# Validate specific plugin
pets validate --plugin jira

# Validate with custom directory
pets validate --all --directory ./my-plugins

list

List available pets from local opencode.json file.

Options:

• -d, --directory <path> - Specify directory to search for opencode.json (default: .)

Examples:

# List pets from current directory
pets list

# List from custom directory
pets list --directory ./config

info

Run validation and list available pets in one command.

Options:

• -d, --directory <path> - Specify directory to search (default: .)
• -p, --pets-dir <path> - Specify pets directory (default: ./pets)

Examples:

# Run validation and list pets
pets info

# Use custom directories
pets info --directory ./config --pets-dir ./my-plugins

init

Create a new pets.json configuration file.

Options:

• -d, --directory <path> - Specify directory to create pets.json (default: .)
• -f, --force - Overwrite existing pets.json
• -t, --template <type> - Template to use: basic, full, development (default: basic)

Templates:

• basic: Minimal configuration with version and plugins array
• full: Complete configuration with settings and metadata
• development: Development-focused configuration with sample plugins

Examples:

# Create basic configuration
pets init

# Create full configuration with settings
pets init --template full

# Overwrite existing configuration
pets init --force --template development

config

Manage pets.json configuration settings.

Options:

• -d, --directory <path> - Specify directory with pets.json (default: .)
• -s, --set <key=value> - Set configuration value
• -g, --get <key> - Get configuration value
• -l, --list - List all configuration

Examples:

# Show all configuration
pets config --list

# Get specific setting
pets config --get settings.autoValidate

# Set configuration value
pets config --set settings.autoValidate=true

# Set nested value
pets config --set settings.defaultPetsDirectory="./my-pets"

add

Add a plugin to pets.json configuration.

Options:

• -d, --directory <path> - Specify directory with pets.json (default: .)
• -p, --plugin <path> - Plugin path to add (required)
• -n, --name <name> - Plugin name (optional, auto-detected)
• -e, --enabled - Enable plugin (default: true)

Examples:

# Add plugin with auto-detected name
pets add --plugin ./pets/jira

# Add plugin with custom name
pets add --plugin ./custom/path --name my-plugin

# Add disabled plugin
pets add --plugin ./pets/gitlab --enabled false

remove

Remove a plugin from pets.json configuration.

Options:

• -d, --directory <path> - Specify directory with pets.json (default: .)
• -p, --plugin <path> - Plugin path to remove
• -n, --name <name> - Plugin name to remove

Examples:

# Remove by path
pets remove --plugin ./pets/jira

# Remove by name
pets remove --name jira

show

Display current pets.json configuration in a readable format.

Options:

• -d, --directory <path> - Specify directory with pets.json (default: .)

Examples:

# Show current configuration
pets show

# Show configuration from custom directory
pets show --directory ./config

help

Show help information.

Usage Examples

Basic Workflow

# 1. Build CLI
npm run build-cli

# 2. Create local configuration
./pets.sh init --template full

# 3. Add plugins to local config
./pets.sh add --plugin ./pets/jira --name jira
./pets.sh add --plugin ./pets/gitlab --name gitlab

# 4. Check all plugins are valid
./pets.sh validate --all

# 5. See what pets are configured locally
./pets.sh show

# 6. Get combined validation and listing
./pets.sh info

Development Workflow

# Create development configuration with sample plugins
./pets.sh init --template development

# Validate a single plugin during development
./pets.sh validate --plugin my-new-plugin

# Check current directory plugin
./pets.sh validate

# Add new plugin to local config
./pets.sh add --plugin ./my-plugin --name my-plugin

# Configure settings
./pets.sh config --set settings.autoValidate=false

# Test with different configurations
./pets.sh list --directory ./test-config

Configuration Management

# Initialize new configuration
./pets.sh init --template full

# Add plugins
./pets.sh add --plugin ./pets/jira --name "Jira Plugin"
./pets.sh add --plugin ./pets/gitlab --name "GitLab Plugin"

# Manage configuration
./pets.sh config --list
./pets.sh config --get settings.autoValidate
./pets.sh config --set settings.defaultPetsDirectory="./my-plugins"

# Remove plugins
./pets.sh remove --name "Jira Plugin"

# Show current state
./pets.sh show

Development Workflow

# Validate a single plugin during development
./pets.sh validate --plugin my-new-plugin

# Check current directory plugin
./pets.sh validate

# Test with different configurations
./pets.sh list --directory ./test-config

Output

The CLI provides clear, emoji-enhanced output:

• ✅ Success indicators
• ❌ Error indicators
• ⚠️ Warning indicators
• 🔍 Search/validation indicators
• 🐾 Pet-related information
• 📋 Report headers

Integration with OpenCode

The CLI integrates seamlessly with OpenCode workflows:

1. Validation First: Always run validation before using plugins
2. Configuration Discovery: Automatically reads opencode.json for available pets
3. Development Support: Helps ensure plugin quality during development

pets.json Configuration Format

The pets.json file allows local configuration of plugins:

Basic Structure

{
  "version": "1.0.0",
  "created": "2025-11-19T15:39:56.996Z",
  "plugins": [
    {
      "name": "jira",
      "path": "./pets/jira",
      "enabled": true,
      "description": "Jira integration plugin",
      "added": "2025-11-19T15:40:00.000Z"
    }
  ]
}

Full Structure

{
  "version": "1.0.0",
  "created": "2025-11-19T15:39:56.996Z",
  "description": "Local pets configuration",
  "settings": {
    "autoValidate": true,
    "showWarnings": true,
    "defaultPetsDirectory": "./pets"
  },
  "plugins": [
    {
      "name": "jira",
      "path": "./pets/jira",
      "enabled": true,
      "description": "Jira & Confluence integration",
      "added": "2025-11-19T15:40:00.000Z"
    }
  ]
}

Plugin Object Properties

• name: Plugin identifier (string, required)
• path: Relative or absolute path to plugin (string, required)
• enabled: Whether plugin is active (boolean, default: true)
• description: Plugin description (string, optional)
• added: When plugin was added (ISO date string, auto-generated)

Settings Properties

• autoValidate: Automatically validate plugins on operations (boolean, default: true)
• showWarnings: Show validation warnings (boolean, default: true)
• defaultPetsDirectory: Default directory to search for plugins (string, default: "./pets")

File Structure

The CLI expects this structure:

project/
├── pets.json             # Local plugin configuration
├── opencode.json          # OpenCode configuration (optional)
├── pets/                  # Plugin directory
│   ├── plugin1/
│   │   ├── package.json
│   │   ├── index.ts
│   │   └── opencode.json
│   └── plugin2/
│       ├── package.json
│       ├── index.ts
│       └── opencode.json
└── src/core/
    ├── cli.js             # Compiled CLI
    └── cli.ts             # CLI source

Error Handling

The CLI provides helpful error messages for common issues:

• Missing opencode.json files
• Invalid plugin structure
• Missing required files
• JSON syntax errors
• Missing dependencies

Contributing

To extend the CLI:

1. Edit src/core/cli.ts for new commands
2. Update src/core/validate-plugin.ts for validation logic
3. Rebuild with npm run build-cli
4. Test with ./pets.sh help