# Plugin Commands

Complete plugin management system with dependency resolution, security scanning, health checks, and cron task support.

## List Plugins

The `pteroca:plugin:list` command displays all registered plugins with their current state and detailed information.

* **Command:** `pteroca:plugin:list`
* **Alias:** `plugin:list` (deprecated, removed in v1.0.0)

### Options

* `--state, -s[=STATE]`: Filter by state (`enabled`, `disabled`, `faulted`)

### Examples

```bash
# Recommended (v0.6+)
php bin/console pteroca:plugin:list

# Filter by enabled plugins
php bin/console pteroca:plugin:list --state=enabled

# Deprecated (still works until v1.0.0)
php bin/console plugin:list
```

## Enable Plugin

The `pteroca:plugin:enable` command enables a plugin with optional dependency resolution and circular dependency detection.

* **Command:** `pteroca:plugin:enable`
* **Alias:** `plugin:enable` (deprecated, removed in v1.0.0)

### Arguments

* `plugin` (required): Plugin name to enable

### Options

* `--with-dependencies, -d`: Automatically enable required dependencies
* `--force, -f`: Force enable without dependency checks (DANGEROUS)

### Examples

```bash
# Recommended (v0.6+)
php bin/console pteroca:plugin:enable my-plugin

# Enable with dependencies
php bin/console pteroca:plugin:enable my-plugin --with-dependencies

# Deprecated (still works until v1.0.0)
php bin/console plugin:enable my-plugin
```

### Features

* Dependency resolution with semantic versioning support
* Circular dependency detection
* Automatic dependency enabling with `--with-dependencies` flag
* Safety checks to prevent invalid plugin states

## Disable Plugin

The `pteroca:plugin:disable` command disables a plugin with optional cascade disable of dependents.

* **Command:** `pteroca:plugin:disable`
* **Alias:** `plugin:disable` (deprecated, removed in v1.0.0)

### Arguments

* `plugin` (required): Plugin name to disable

### Options

* `--cascade, -c`: Also disable all plugins that depend on this plugin

### Examples

```bash
# Recommended (v0.6+)
php bin/console pteroca:plugin:disable my-plugin

# Disable with cascade (disable dependents too)
php bin/console pteroca:plugin:disable my-plugin --cascade

# Deprecated (still works until v1.0.0)
php bin/console plugin:disable my-plugin
```

## Uninstall Plugin

The `pteroca:plugin:uninstall` command completely removes a plugin from the system, including database records, settings, and optionally the plugin files.

* **Command:** `pteroca:plugin:uninstall`
* **Alias:** `plugin:uninstall` (deprecated, removed in v1.0.0)

### Arguments

* `plugin` (required): Plugin name to uninstall

### Options

* `--keep-files, -k`: Keep plugin files on filesystem, only remove from database

### Examples

```bash
# Recommended (v0.6+)
php bin/console pteroca:plugin:uninstall my-plugin

# Uninstall but keep files (useful for backup or debugging)
php bin/console pteroca:plugin:uninstall my-plugin --keep-files

# Deprecated (still works until v1.0.0)
php bin/console plugin:uninstall my-plugin
```

### Interactive Confirmation

The command provides two-step confirmation:

1. **Uninstallation Confirmation**: Displays plugin information and confirms the uninstall operation
2. **File Deletion Prompt**: Asks whether to delete plugin files from filesystem (unless `--keep-files` is used)

### What It Does

* Checks for enabled dependent plugins (blocks uninstallation if found)
* Disables the plugin if it's currently enabled
* Removes plugin database record
* Deletes all plugin settings
* Optionally deletes plugin directory from filesystem
* Clears cache and rebuilds plugin registry

{% hint style="warning" %}
Unlike the disable command, uninstall is **permanent** and removes all plugin data. Make sure you have backups if needed. Use `--keep-files` to preserve plugin files for potential reinstallation.
{% endhint %}

## Scan for Plugins

The `pteroca:plugin:scan` command scans the plugins directory for new or updated plugins and displays discovered plugin manifests.

* **Command:** `pteroca:plugin:scan`
* **Alias:** `plugin:scan` (deprecated, removed in v1.0.0)

### Examples

```bash
# Recommended (v0.6+)
php bin/console pteroca:plugin:scan

# Deprecated (still works until v1.0.0)
php bin/console plugin:scan
```

### What It Does

* Scans the plugins directory for valid plugin.json manifests
* Reports discovered plugins with version and status
* Identifies invalid manifests
* Does not automatically enable plugins

## Show Plugin Dependencies

The `pteroca:plugin:deps` command analyzes and displays plugin dependencies, detects circular dependencies, and shows topological load order.

* **Command:** `pteroca:plugin:deps`
* **Alias:** `plugin:deps` (deprecated, removed in v1.0.0)

### Arguments

* `plugin` (optional): Plugin name (shows all plugins if omitted)

### Options

* `--tree, -t`: Show full dependency tree
* `--dependents, -d`: Show plugins that depend on this plugin

### Examples

```bash
# Recommended (v0.6+)
php bin/console pteroca:plugin:deps

# Show dependencies for specific plugin
php bin/console pteroca:plugin:deps my-plugin

# Show full dependency tree
php bin/console pteroca:plugin:deps my-plugin --tree

# Show dependents (reverse dependencies)
php bin/console pteroca:plugin:deps my-plugin --dependents

# Deprecated (still works until v1.0.0)
php bin/console plugin:deps my-plugin
```

### Features

* Dependency tree visualization
* Circular dependency detection
* Topological load order display
* Reverse dependency tracking (what depends on this plugin)

## Install Plugin Dependencies

The `pteroca:plugin:install-deps` command installs Composer dependencies for plugins with production flags.

* **Command:** `pteroca:plugin:install-deps`
* **Alias:** `plugin:install-deps` (deprecated, removed in v1.0.0)

### Arguments

* `plugin` (optional): Plugin name to install dependencies for (omit for --all)

### Options

* `--all, -a`: Install dependencies for all plugins with composer.json
* `--clean, -c`: Remove vendor/ directory before installation

### Examples

```bash
# Recommended (v0.6+)
php bin/console pteroca:plugin:install-deps my-plugin

# Install for all plugins
php bin/console pteroca:plugin:install-deps --all

# Clean install
php bin/console pteroca:plugin:install-deps my-plugin --clean

# Deprecated (still works until v1.0.0)
php bin/console plugin:install-deps my-plugin
```

### Composer Flags Used

* `--no-dev`: Production dependencies only
* `--no-plugins`: Disable Composer plugins
* `--no-scripts`: Don't run scripts

### Validates

* composer.json file existence
* composer.json syntax

## Publish Plugin Assets

The `pteroca:plugin:assets:publish` command publishes assets (CSS, JS, images) from plugin directories to the public folder.

* **Command:** `pteroca:plugin:assets:publish`
* **Alias:** `plugin:assets:publish` (deprecated, removed in v1.0.0)

### Options

* `--plugin, -p[=PLUGIN]`: Publish assets for specific plugin (publishes all enabled plugins if omitted)

### Examples

```bash
# Recommended (v0.6+)
php bin/console pteroca:plugin:assets:publish

# Publish for specific plugin
php bin/console pteroca:plugin:assets:publish --plugin=my-plugin

# Deprecated (still works until v1.0.0)
php bin/console plugin:assets:publish
```

## Rebuild Plugin Cache

The `plugin:rebuild-cache` command rebuilds the enabled plugins cache to ensure the system has the latest plugin state information.

* **Command:** `plugin:rebuild-cache`

### Examples

```bash
php bin/console plugin:rebuild-cache
```

### When to Use

Use this command when:

* Plugins are not being detected after enabling/disabling
* Plugin state seems inconsistent
* After manually modifying plugin files
* After database changes affecting plugin records
* As part of troubleshooting plugin issues

### What It Does

* Clears the current enabled plugins cache
* Rebuilds the cache from the database
* Updates the plugin registry with current state
* Ensures all enabled plugins are properly indexed

{% hint style="info" %}
This command is automatically run when enabling or disabling plugins, but can be useful for troubleshooting or after manual changes.
{% endhint %}

## Check Plugin Health

The `pteroca:plugin:health:check` command runs health checks on plugins and reports overall health percentage.

* **Command:** `pteroca:plugin:health:check`
* **Alias:** `plugin:health:check` (deprecated, removed in v1.0.0)

### Arguments

* `plugin-name` (optional): Plugin name to check (checks all enabled plugins if omitted)

### Options

* `--all, -a`: Check all plugins including disabled ones

### Examples

```bash
# Recommended (v0.6+)
php bin/console pteroca:plugin:health:check

# Check specific plugin
php bin/console pteroca:plugin:health:check my-plugin

# Check all plugins including disabled
php bin/console pteroca:plugin:health:check --all

# Deprecated (still works until v1.0.0)
php bin/console plugin:health:check
```

## Security Scan

The `pteroca:plugin:security:scan` command scans plugins for security vulnerabilities and reports findings by severity level.

* **Command:** `pteroca:plugin:security:scan`
* **Alias:** `plugin:security:scan` (deprecated, removed in v1.0.0)

### Arguments

* `plugin-name` (optional): Plugin name to scan (scans all enabled plugins if omitted)

### Options

* `--severity, -s[=LEVEL]`: Filter by severity level (`critical`, `high`, `medium`, `low`)
* `--all, -a`: Scan all plugins including disabled ones

### Examples

```bash
# Recommended (v0.6+)
php bin/console pteroca:plugin:security:scan

# Scan specific plugin
php bin/console pteroca:plugin:security:scan my-plugin

# Filter by critical issues only
php bin/console pteroca:plugin:security:scan --severity=critical

# Deprecated (still works until v1.0.0)
php bin/console plugin:security:scan
```

### Security Checks

What it scans for:

* Dangerous code patterns
* SQL injection risks
* Path traversal vulnerabilities
* Insecure file operations
* Command injection risks

## List Cron Tasks

The `pteroca:plugin:cron:list` command displays all registered plugin cron tasks with status, schedule, and next run time.

* **Command:** `pteroca:plugin:cron:list`
* **Alias:** `plugin:cron:list` (deprecated, removed in v1.0.0)

### Options

* `--enabled-only`: Show only enabled tasks
* `--plugin, -p[=PLUGIN]`: Filter by plugin name

### Examples

```bash
# Recommended (v0.6+)
php bin/console pteroca:plugin:cron:list

# Show only enabled tasks
php bin/console pteroca:plugin:cron:list --enabled-only

# Filter by plugin
php bin/console pteroca:plugin:cron:list --plugin=my-plugin

# Deprecated (still works until v1.0.0)
php bin/console plugin:cron:list
```

## Run Cron Tasks

The `pteroca:plugin:cron:run` command executes due cron tasks or a specific task, with execution reporting.

* **Command:** `pteroca:plugin:cron:run`
* **Alias:** `plugin:cron:run` (deprecated, removed in v1.0.0)

### Arguments

* `task` (optional): Specific task name to run (format: `plugin-name:task-name`)

### Options

* `--force, -f`: Force run even if task is not due
* `--dry-run`: Show what would run without executing

### Examples

```bash
# Recommended (v0.6+)
php bin/console pteroca:plugin:cron:run

# Run specific task
php bin/console pteroca:plugin:cron:run my-plugin:cleanup

# Force run specific task
php bin/console pteroca:plugin:cron:run my-plugin:cleanup --force

# Dry run to see what would execute
php bin/console pteroca:plugin:cron:run --dry-run

# Deprecated (still works until v1.0.0)
php bin/console plugin:cron:run
```

## Reset Plugin

The `pteroca:plugin:reset` command resets a faulted plugin back to registered state to allow re-enabling after issues are fixed. This command also fixes plugins stuck in the discovered state (detected by the system but unable to register).

* **Command:** `pteroca:plugin:reset`
* **Alias:** `plugin:reset` (deprecated, removed in v1.0.0)

### Arguments

* `plugin` (required): Plugin name to reset

### Examples

```bash
# Recommended (v0.6+)
php bin/console pteroca:plugin:reset my-plugin

# Deprecated (still works until v1.0.0)
php bin/console plugin:reset my-plugin
```

## Related Guides

* [CLI Commands Overview](/for-developers/cli-reference/cli-reference.md) - Command reference home
* [Plugin Development](https://github.com/PteroCA-Org/pteroca-homepage/blob/docs/for-developers/plugins/README.md) - Create plugins
* [Cron Scheduler](/for-developers/cli-reference/cron-scheduler.md) - Automated plugin cron tasks


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.pteroca.com/for-developers/cli-reference/plugin-commands.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.