### Full Example: Creating a Custom Server Status Command

Source: https://github.com/ploi/cli/blob/main/_autodocs/api-reference/Command.md

This example demonstrates creating a custom command to check server status, utilizing EnsureHasToken and InteractWithServer traits, and displaying server details in a table.

```php
<?php

namespace App\Commands\Server;

use App\Commands\Command;
use App\Commands\Concerns\InteractWithServer;
use App\Traits\EnsureHasToken;

class StatusCommand extends Command
{
    use EnsureHasToken, InteractWithServer;

    protected $signature = 'server:status {--server=}';
    
    protected $description = 'Check the status of a server';

    public function handle(): void
    {
        $this->ensureHasToken();

        $serverId = $this->getServerId();
        
        $this->info('Fetching server status...');
        
        $server = $this->ploi->getServerDetails($serverId)['data'];

        $this->newLine();
        $this->table(
            ['Property', 'Value'],
            [
                ['Name', $server['name']],
                ['IP Address', $server['ip_address']],
                ['Status', $server['status']],
                ['Plan', $server['plan']],
                ['Provider', $server['provider']],
            ]
        );

        $statusColor = $server['status'] === 'active' ? 'green' : 'yellow';
        $this->line("<fg={$statusColor}>Server is {$server['status']}</>");
    }
}
```

--------------------------------

### Run Initialization Command

Source: https://github.com/ploi/cli/blob/main/_autodocs/configuration.md

Initiate the Ploi CLI setup process by running the init command.

```bash
./ploi init
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/ploi/cli/blob/main/CLAUDE.md

Use Composer to install the project's dependencies.

```bash
composer install
```

--------------------------------

### Command Registration and Invocation Examples

Source: https://github.com/ploi/cli/blob/main/_autodocs/api-reference/Command.md

Understand how commands are automatically registered and how their signatures determine their invocation syntax.

```text
// Command signature: site:create
// Usage: ./ploi site:create

// Command signature: server:restart {--force}
// Usage: ./ploi server:restart --force

// Command signature: deploy {--server=} {--site=}
// Usage: ./ploi deploy --server=1 --site=2
```

--------------------------------

### Install Site Repository

Source: https://github.com/ploi/cli/blob/main/_autodocs/api-reference/PloiAPI.md

Installs a Git repository on a specified site. Requires server ID, site ID, and repository data including provider, repository URL, and branch.

```APIDOC
## installRepository

### Description
Installs a Git repository on a site.

### Method
POST

### Endpoint
/servers/{serverId}/sites/{siteId}/repository

### Parameters
#### Path Parameters
- **serverId** (int) - Yes - Server ID
- **siteId** (int) - Yes - Site ID

#### Request Body
- **data** (array) - Yes - Repository data (provider, repository, branch)
```

--------------------------------

### YAML Serialization Example

Source: https://github.com/ploi/cli/blob/main/_autodocs/api-reference/Configuration.md

Illustrates how configuration files are wrapped with their type key and how empty arrays are serialized.

```yaml
# settings.yml
settings:
  server: "123"

# provision.yml
provision:
  commands: []
  services: []
```

--------------------------------

### site:repository:install

Source: https://github.com/ploi/cli/blob/main/_autodocs/commands.md

Connects a Git repository to a specified site on the server, enabling deployment integration.

```APIDOC
## site:repository:install

### Description
Connects a Git repository to the site for deployment.

### Method
Not applicable (CLI command)

### Endpoint
Not applicable (CLI command)

### Parameters
#### Options
- `--server=ID` (string) - Required - Server ID or name
- `--site=DOMAIN` (string) - Required - Site domain

### Request Example
```bash
ploi site:repository:install --server=123 --site=example.com
```

### Response
(CLI output confirming repository installation)
```

--------------------------------

### Full Command Structure Example

Source: https://github.com/ploi/cli/blob/main/_autodocs/api-reference/Command.md

Illustrates a complete command structure, including namespace, trait usage, signature, description, and the `handle` method. It shows how to use `ensureHasToken`, access `$ploi` for API calls, and `$configuration` for settings.

```php
<?php

namespace App\Commands\MyNamespace;

use App\Commands\Command;
use App\Traits\EnsureHasToken;

class MyCommand extends Command
{
    use EnsureHasToken;

    // Command signature and options
    protected $signature = 'command:name {--option=}';
    
    // Command description for help output
    protected $description = 'Description of what this command does';

    public function handle(): void
    {
        // Ensure user is authenticated
        $this->ensureHasToken();

        // Use API
        $servers = $this->ploi->getServerList()['data'];

        // Use configuration
        $serverId = $this->configuration->get('settings.server');

        // Output
        $this->success('Command executed successfully!');
    }
}
```

--------------------------------

### Install and Authenticate Ploi CLI

Source: https://github.com/ploi/cli/blob/main/_autodocs/README.md

Download the Ploi CLI, make it executable, and set your API token to authenticate. Verify the authentication by listing servers.

```bash
# Download and make executable
chmod +x ./ploi

# Set your API token
./ploi token

# Verify authentication
./ploi server:list
```

--------------------------------

### site:secure

Source: https://github.com/ploi/cli/blob/main/_autodocs/commands.md

Installs a Let's Encrypt SSL certificate for a specified site on the server.

```APIDOC
## site:secure

### Description
Requests and installs a free Let's Encrypt SSL certificate for a site.

### Method
Not applicable (CLI command)

### Endpoint
Not applicable (CLI command)

### Parameters
#### Options
- `--server=ID` (string) - Required - Server ID or name
- `--site=DOMAIN` (string) - Required - Site domain
- `--certificate=ID` (string) - Optional - Certificate ID

### Request Example
```bash
ploi site:secure --server=123 --site=example.com
```

### Response
(CLI output confirming SSL certificate installation)
```

--------------------------------

### Accessing and Modifying Settings in Commands

Source: https://github.com/ploi/cli/blob/main/_autodocs/api-reference/Configuration.md

Demonstrates how to instantiate the Configuration class within a command to get and set project settings, including saving changes.

```php
use App\Support\Configuration;

class MyCommand extends Command
{
    public function handle()
    {
        $config = new Configuration();
        
        // Get current project's server and site
        $serverId = $config->get('settings.server');
        $siteId = $config->get('settings.site');
        
        // Modify and save
        $config->set('settings.domain', 'newdomain.com');
        $config->store(getcwd() . '/.ploi/settings.yml', 'settings');
    }
```

--------------------------------

### Check for Installed Git Repository

Source: https://github.com/ploi/cli/blob/main/_autodocs/api-reference/Traits.md

Verifies if a Git repository is installed for a given server and site. If not, it provides instructions on how to install one. Use this before attempting Git-related operations.

```php
use App\Commands\Command;
use App\Traits\EnsureHasToken;
use App\Traits\HasRepo;

class DeployCommand extends Command
{
    use EnsureHasToken, HasRepo;

    public function handle()
    {
        $this->ensureHasToken();

        if (!$this->hasRepoInstalled($serverId, $siteId)) {
            $this->error('Git repository not installed. Install one first:');
            $this->info('./ploi site:install:repo --server=' . $serverId . ' --site=' . $siteId);
            exit(1);
        }

        // Proceed with deployment
    }
}
```

--------------------------------

### Example Command Usage

Source: https://github.com/ploi/cli/blob/main/_autodocs/README.md

Demonstrates how to extend the abstract Command class to create a custom CLI command. It shows accessing the Ploi API client and configuration manager, and using output methods.

```php
class MyCommand extends Command
{
    protected $signature = 'my:command';
    
    public function handle()
    {
        $servers = $this->ploi->getServerList()['data'];
        $this->success('Loaded ' . count($servers) . ' servers');
    }
}
```

--------------------------------

### Define Custom Configuration File

Source: https://github.com/ploi/cli/blob/main/_autodocs/configuration.md

Example of a custom configuration file (config/custom.php) defining API URL and timeout, with fallbacks to environment variables.

```php
// config/custom.php
return [
    'api_url' => env('PLOI_API_URL', 'https://ploi.io/api'),
    'timeout' => env('PLOI_TIMEOUT', 30),
];
```

--------------------------------

### Custom Command Example

Source: https://github.com/ploi/cli/blob/main/_autodocs/api-reference/Command.md

Demonstrates how to extend the abstract Command class to create a custom CLI command. It shows how to define the command signature and description, and access the `$ploi` and `$configuration` properties within the `handle` method.

```php
use App\Commands\Command;

class MyCommand extends Command
{
    protected $signature = 'my:command';
    protected $description = 'My custom command';

    public function handle()
    {
        // $this->ploi is automatically available
        // $this->configuration is automatically available
    }
}
```

--------------------------------

### Get and Set Configuration in Commands

Source: https://github.com/ploi/cli/blob/main/_autodocs/configuration.md

Demonstrates how to retrieve and modify configuration settings within a custom command using the Configuration class. Settings can be stored in a local file.

```php
use App\Support\Configuration;

class MyCommand extends Command
{
    public function handle()
    {
        $config = new Configuration();

        // Get settings
        $serverId = $config->get('settings.server');
        $siteId = $config->get('settings.site');
        $domain = $config->get('settings.domain');

        // Get provision config
        $commands = $config->get('provision.commands');
        $services = $config->get('provision.services');

        // Set values
        $config->set('settings.domain', 'newdomain.com');
        $config->store(getcwd() . '/.ploi/settings.yml', 'settings');
    }
}
```

--------------------------------

### Configuration Reference

Source: https://github.com/ploi/cli/blob/main/_autodocs/INDEX.md

Manages project configuration through YAML files, supporting get, set, and store operations.

```APIDOC
## Configuration Reference

### Description
This section details the management of project configuration using YAML files. It covers operations for retrieving, setting, and storing configuration values, essential for customizing Ploi CLI behavior and project settings.

### Operations
- Get configuration values
- Set configuration values
- Store configuration changes

### Configuration Files
- YAML files
```

--------------------------------

### Complete Authentication and Configuration Flow

Source: https://github.com/ploi/cli/blob/main/_autodocs/api-reference/Traits.md

Ensures that an authentication token is present and checks for an existing Ploi configuration file. This is a common setup step for commands interacting with the Ploi API.

```php
use App\Commands\Command;
use App\Traits\EnsureHasToken;
use App\Traits\HasPloiConfiguration;

class MyCommand extends Command
{
    use EnsureHasToken, HasPloiConfiguration;

    public function handle()
    {
        // Validate token first
        $this->ensureHasToken();

        // Check for project config
        if ($this->hasPloiConfigurationFile()) {
            $serverId = $this->configuration->get('settings.server');
            $this->info("Using configured server: $serverId");
        } else {
            $this->warn('No .ploi/settings.yml found. Please initialize first.');
        }
    }
}
```

--------------------------------

### get

Source: https://github.com/ploi/cli/blob/main/_autodocs/api-reference/Configuration.md

Retrieves a configuration value using dot notation. This method can fetch entire configuration sections or specific nested values, with an option to provide a default value if the key is not found.

```APIDOC
## get

### Description
Retrieves a configuration value using dot notation. Can fetch entire config types or specific nested values. Returns a default value if the key is not found.

### Method
`get(string $key, $default = null): mixed`

### Parameters
#### Path Parameters
- **key** (string) - Required - Configuration key (e.g., 'settings.server', 'provision.commands') or config type (e.g., 'settings')
- **default** (mixed) - Optional - Default value if key not found

### Return Type
mixed - Configuration value or default

### Throws
InvalidArgumentException - if key is malformed

### Example
```php
$config = new Configuration();

// Get entire config type
$settings = $config->get('settings');

// Get nested value
$serverId = $config->get('settings.server');

// With default value
$value = $config->get('settings.custom_key', 'default_value');
```
```

--------------------------------

### Get Domain Suggestions with Selection

Source: https://github.com/ploi/cli/blob/main/_autodocs/api-reference/Traits.md

Suggests similar domains using fuzzy matching and returns the user's selection. Use this when a user input might be a typo and you need to offer valid alternatives from a predefined list.

```php
use App\Traits\DomainSuggestions;

class MySiteCommand extends Command
{
    use DomainSuggestions;

    public function handle()
    {
        $availableDomains = ['example.com', 'staging.example.com', 'api.example.com'];
        
        $userInput = 'example.com';  // Typo
        
        $selected = $this->getDomainSuggestionsWithSelection(
            $userInput,
            $availableDomains
        );
        
        if ($selected) {
            // Use selected domain
            $this->info("Using domain: {$selected}");
        } else {
            // User rejected all suggestions
            $this->error("Domain not found.");
        }
    }
}
```

--------------------------------

### Project Initialization and Deployment using Config

Source: https://github.com/ploi/cli/blob/main/_autodocs/commands.md

Initializes a project and subsequently deploys using settings from the .ploi/settings.yml configuration file.

```bash
cd /path/to/project
./ploi init
./ploi deploy
```

--------------------------------

### Initialize a Project with Ploi CLI

Source: https://github.com/ploi/cli/blob/main/_autodocs/README.md

Navigate to your project directory and run the `init` command to set up project configuration files. This creates `settings.yml` and `provision.yml`.

```bash
cd /path/to/project
./ploi init

# Creates:
# .ploi/settings.yml (server, site, domain)
# .ploi/provision.yml (for provisioning)
```

--------------------------------

### initialize

Source: https://github.com/ploi/cli/blob/main/_autodocs/api-reference/Configuration.md

Initializes new project configuration files with server, site, and domain information. This method creates the necessary `.ploi/` directory and its default configuration files if they do not exist.

```APIDOC
## initialize

### Description
Initializes new project configuration files with server, site, and domain information. Creates the `.ploi/` directory and its default configuration files if they do not exist.

### Method
`initialize(string $server, string $site, string $path, string $domain): void`

### Parameters
#### Path Parameters
- **server** (string) - Required - Server ID
- **site** (string) - Required - Site ID
- **path** (string) - Required - Project root path where `.ploi/` directory will be created
- **domain** (string) - Required - Site domain name

### Example
```php
$config = new Configuration();
$config->initialize(
    server: '123',
    site: '456',
    path: '/var/www/myproject',
    domain: 'example.com'
);
```
```

--------------------------------

### Get System Users

Source: https://github.com/ploi/cli/blob/main/_autodocs/api-reference/Concerns.md

Fetches all system users associated with the currently selected server.

```php
$users = $this->systemUsers();
// [
//   ['id' => 1, 'name' => 'ploi', 'sudo' => false],
//   ['id' => 2, 'name' => 'deploy', 'sudo' => true],
// ]
```

--------------------------------

### Create Server with Custom Mode

Source: https://github.com/ploi/cli/blob/main/_autodocs/configuration.md

Initiate server creation using the custom mode with the --custom flag.

```bash
./ploi server:create --custom
```

--------------------------------

### Deployment with Options

Source: https://github.com/ploi/cli/blob/main/_autodocs/commands.md

Executes a deployment command with specified server and site options.

```bash
./ploi deploy --server="production" --site="example.com"
```

--------------------------------

### Initialize New Project Configuration

Source: https://github.com/ploi/cli/blob/main/_autodocs/api-reference/Configuration.md

Initializes new project configuration files (`settings.yml` and `provision.yml`) within the specified path. Creates the .ploi/ directory if it does not exist. Requires server, site, path, and domain details.

```php
$config = new Configuration();
$config->initialize(
    server: '123',
    site: '456',
    path: '/var/www/myproject',
    domain: 'example.com'
);
```

--------------------------------

### Retrieve Project Settings using Configuration Class

Source: https://github.com/ploi/cli/blob/main/_autodocs/configuration.md

Demonstrates how to access project settings like server ID, site ID, and domain from the `.ploi/settings.yml` file using the `Configuration` class.

```php
$config = new Configuration();
$serverId = $config->get('settings.server');  // "123"
$siteId = $config->get('settings.site');      // "456"
$domain = $config->get('settings.domain');    // "example.com"
```

--------------------------------

### Get Server ID

Source: https://github.com/ploi/cli/blob/main/_autodocs/api-reference/Concerns.md

Retrieves the server ID, prioritizing configuration, command options, or interactive selection.

```php
$serverId = $this->getServerId();
// Returns server ID from one of three sources above
```

--------------------------------

### Ploi API Authentication Error

Source: https://github.com/ploi/cli/blob/main/_autodocs/api-reference/PloiAPI.md

Example of an authentication error message returned by the Ploi API when an invalid token is used.

```text
==> The given API key is incorrect. Use 'ploi token --force' to set a new one.
```

--------------------------------

### Get Test Domain

Source: https://github.com/ploi/cli/blob/main/_autodocs/api-reference/PloiAPI.md

Retrieves the test domain information for a specific site. Requires server ID and site ID.

```APIDOC
## getTestDomain

### Description
Retrieves test domain information for a site.

### Method
GET

### Endpoint
/servers/{serverId}/sites/{siteId}/test-domain

### Parameters
#### Path Parameters
- **serverId** (int) - Yes - Server ID
- **siteId** (int) - Yes - Site ID
```

--------------------------------

### Site Deployment with Command Options Fallback

Source: https://github.com/ploi/cli/blob/main/_autodocs/api-reference/Concerns.md

This snippet shows how to deploy a site using command-line options for server and site identification. If options are not provided, it falls back to an interactive selection process.

```php
class DeployCommand extends Command
{
    protected $signature = 'deploy {--server=} {--site=} {--schedule=}';

    use InteractWithServer, InteractWithSite;

    public function handle()
    {
        // If options provided, use them
        if ($this->option('server') && $this->option('site')) {
            $serverId = $this->getServerIdByNameOrIp($this->option('server'));
            $siteId = $this->getSiteIdByDomain($serverId, $this->option('site'));
        }
        // Otherwise, interactive selection
        else {
            [$serverId, $siteId] = $this->getServerAndSite();
        }

        // Deploy
        $this->ploi->deploySite($serverId, $siteId, [
            'schedule' => $this->option('schedule')
        ]);

        $this->success('Deployment scheduled!');
    }
}
```

--------------------------------

### Get Server and Site IDs

Source: https://github.com/ploi/cli/blob/main/_autodocs/api-reference/Concerns.md

Retrieves both server and site IDs, prioritizing configuration, command options, or interactive selection.

```php
[$serverId, $siteId] = $this->getServerAndSite();
```

--------------------------------

### Get Site Repository

Source: https://github.com/ploi/cli/blob/main/_autodocs/api-reference/PloiAPI.md

Retrieves the repository information associated with a specific site on a server. Requires server ID and site ID.

```APIDOC
## getRepository

### Description
Retrieves repository information for a site.

### Method
GET

### Endpoint
/servers/{serverId}/sites/{siteId}/repository

### Parameters
#### Path Parameters
- **serverId** (int) - Yes - Server ID
- **siteId** (int) - Yes - Site ID
```

--------------------------------

### Get Site Details

Source: https://github.com/ploi/cli/blob/main/_autodocs/api-reference/PloiAPI.md

Retrieves detailed information for a specific site on a given server, including deployment logs, status, and certificates.

```APIDOC
## getSiteDetails

### Description
Retrieves detailed information for a specific site.

### Method
GET

### Endpoint
/servers/{serverId}/sites/{siteId}

### Parameters
#### Path Parameters
- **serverId** (int) - Yes - Server ID
- **siteId** (int) - Yes - Site ID

#### Response
#### Success Response (200)
- **site object** (array) - Site object with deployment logs, status, certificates, and other details
```

--------------------------------

### Retrieve Provisioning Scripts and Services

Source: https://github.com/ploi/cli/blob/main/_autodocs/configuration.md

Shows how to retrieve the list of provisioning commands and services from the `.ploi/provision.yml` file using the `Configuration` class.

```php
$config = new Configuration();
$commands = $config->get('provision.commands');
$services = $config->get('provision.services');
```

--------------------------------

### Get Server List

Source: https://github.com/ploi/cli/blob/main/_autodocs/api-reference/PloiAPI.md

Retrieves a paginated list of all servers associated with the Ploi account. Supports filtering results with a search query.

```php
$servers = $api->getServerList(page: 1, search: 'production');
```

--------------------------------

### Get Configuration Types

Source: https://github.com/ploi/cli/blob/main/_autodocs/api-reference/Configuration.md

Retrieves an array of all currently managed configuration type keys. New types can be added using addConfigFile.

```php
$config = new Configuration();
$types = $config->getConfigTypes();
// Result: ['settings', 'provision']

$config->addConfigFile('custom', 'custom.yml');
$types = $config->getConfigTypes();
// Result: ['settings', 'provision', 'custom']
```

--------------------------------

### Instantiate Configuration Service

Source: https://github.com/ploi/cli/blob/main/_autodocs/api-reference/Configuration.md

Initializes the Configuration service. Configuration data is automatically loaded from .ploi/settings.yml and .ploi/provision.yml files if they exist. Defaults to empty arrays if files are missing or unparseable.

```php
use App\Support\Configuration;

$config = new Configuration();
```

--------------------------------

### Create Database Configuration

Source: https://github.com/ploi/cli/blob/main/_autodocs/configuration.md

Configuration for creating a new database.

```php
[
    'name' => 'database_name',
]
```

--------------------------------

### Display Command Help Information

Source: https://github.com/ploi/cli/blob/main/_autodocs/configuration.md

The `--help` global option displays detailed information about a command, including its description, arguments, and options.

```bash
./ploi server:list --help
```

--------------------------------

### Get Server Details

Source: https://github.com/ploi/cli/blob/main/_autodocs/api-reference/PloiAPI.md

Fetches detailed information for a specific server identified by its ID. Supports pagination for related data within the server details.

```php
$serverDetails = $api->getServerDetails(serverId: 123);
```

--------------------------------

### Check if Repository is Installed on Site

Source: https://github.com/ploi/cli/blob/main/_autodocs/api-reference/Traits.md

The `HasRepo` trait provides the `hasRepoInstalled` method to verify if a Git repository is connected to a specific site. This is crucial for deployment commands.

```php
use App\Traits\HasRepo;

class DeployCommand extends Command
{
    use HasRepo;

    public function handle()
    {
        if (!$this->hasRepoInstalled($serverId, $siteId)) {
            $this->error('No repository installed on this site.');
            exit(1);
        }

        // Proceed with deployment
    }
}
```

--------------------------------

### Create Server with Polling

Source: https://github.com/ploi/cli/blob/main/_autodocs/api-reference/Concerns.md

This snippet demonstrates creating a server and then polling its status until it becomes active. It uses interactive text input for the server name and includes error handling for failed creation.

```php
use App\Commands\Command;
use App\Commands\Concerns\InteractWithServer;
use App\Traits\EnsureHasToken;

class CreateServerCommand extends Command
{
    use EnsureHasToken, InteractWithServer;

    public function handle()
    {
        $this->ensureHasToken();

        // Get server name from user
        $serverName = text('Server name:', required: true);

        // Create server
        $server = $this->ploi->createServer([
            'name' => $serverName,
            // ... other options
        ])['data'];

        $this->info('Creating server...');

        // Poll until active
        $success = $this->pollServerStatus($server['id']);

        if ($success) {
            $this->success('Server is ready!');
        } else {
            $this->error('Server creation failed.');
            exit(1);
        }
    }
}
```

--------------------------------

### Get Database Details by Name

Source: https://github.com/ploi/cli/blob/main/_autodocs/api-reference/Concerns.md

Fetches the full details of a database by its name on a given server. Use this to retrieve comprehensive information about a database, such as its ID and type.

```php
$database = $this->getDatabaseDetailsByName($serverId, 'production_db');
echo "ID: " . $database['id'];
echo "Type: " . $database['type'];
```

--------------------------------

### Application Main Configuration

Source: https://github.com/ploi/cli/blob/main/_autodocs/configuration.md

The `config/app.php` file contains core application settings such as name, environment, and service providers.

```php
return [
    'name' => 'Ploi CLI',
    'version' => app('git.version'),
    'env' => 'development',
    'providers' => [
        App\Providers\AppServiceProvider::class,
    ],
];
```

--------------------------------

### Directory Handling for Configuration Files

Source: https://github.com/ploi/cli/blob/main/_autodocs/api-reference/Configuration.md

Demonstrates that the Configuration class automatically creates the .ploi/ directory if it does not exist when storing a file.

```php
$config = new Configuration();
$config->store('/path/to/project/.ploi/settings.yml', 'settings');
// Creates: /path/to/project/.ploi/ with 0755 permissions
```

--------------------------------

### Get User Details

Source: https://github.com/ploi/cli/blob/main/_autodocs/api-reference/Concerns.md

Retrieves the profile information of the currently authenticated user. This is useful for accessing user-specific data like name, email, and plan level within a command.

```php
use App\Commands\Concerns\InteractWithUser;

class MyCommand extends Command
{
    use InteractWithUser;

    public function handle()
    {
        $user = $this->getUserDetails();
        $this->info("Logged in as: {$user['name']}");
        
        if ($user['plan'] === 'Pro') {
            // Pro-only features
        }
    }
}
```

--------------------------------

### createServer

Source: https://github.com/ploi/cli/blob/main/_autodocs/api-reference/PloiAPI.md

Creates a new server instance on Ploi with specified configuration details.

```APIDOC
## createServer

### Description
Creates a new server.

### Method
`createServer(array $data): array`

### Parameters
#### Path Parameters
- **data** (array) - Required - Server configuration (name, plan, region, type, os_type, php_version, database_type, description, webhook_url, install_monitoring, credential, webserver_type)

### Return Type
`array` - Server object with ID
```

--------------------------------

### site:create

Source: https://github.com/ploi/cli/blob/main/_autodocs/commands.md

Initiates an interactive process to create a new site on a server, prompting for domain, web directory, system user, and project type.

```APIDOC
## site:create

### Description
Interactively creates a new site on a server.

### Method
Not applicable (CLI command)

### Endpoint
Not applicable (CLI command)

### Parameters
#### Options
- `--server=ID` (string) - Required - Server ID or name

### Request Example
```bash
ploi site:create --server=123
```

### Response
(CLI prompts for site details and confirmation)
```

--------------------------------

### Basic Command Usage

Source: https://github.com/ploi/cli/blob/main/_autodocs/commands.md

Demonstrates the general pattern for executing Ploi CLI commands.

```bash
./ploi command:name [arguments] [--options]
```

--------------------------------

### Get Database ID

Source: https://github.com/ploi/cli/blob/main/_autodocs/api-reference/Concerns.md

Returns the database ID. It prioritizes the --database command option and falls back to interactive selection if the option is not provided. Use this to retrieve a database identifier for subsequent operations.

```php
$databaseId = $this->getDatabase();
// Usage: ./ploi command --database="my_database"
```

--------------------------------

### Create Site

Source: https://github.com/ploi/cli/blob/main/_autodocs/api-reference/PloiAPI.md

Creates a new site on a specified server. Requires server ID and site data including root domain, web directory, system user, and project type.

```APIDOC
## createSite

### Description
Creates a new site on a server.

### Method
POST

### Endpoint
/servers/{serverId}/sites

### Parameters
#### Path Parameters
- **serverId** (int) - Yes - Server ID

#### Request Body
- **data** (array) - Yes - Site data (root_domain, web_directory, system_user, project_type)
```

--------------------------------

### createTenant

Source: https://github.com/ploi/cli/blob/main/_autodocs/api-reference/PloiAPI.md

Creates a new tenant on a specified server and site.

```APIDOC
## createTenant

### Description
Creates a new tenant.

### Method
Not specified (assumed to be a client-side method call)

### Parameters
#### Path Parameters
- **serverId** (int) - Yes - Server ID
- **siteId** (int) - Yes - Site ID

#### Request Body
- **data** (array) - Yes - Tenant data (domain)
```

--------------------------------

### Instantiate DeploymentLogPoller

Source: https://github.com/ploi/cli/blob/main/_autodocs/api-reference/DeploymentLogPoller.md

Create a new instance of the DeploymentLogPoller service. Requires an initialized PloiAPI client.

```php
use App\Services\DeploymentLogPoller;
use App\Services\PloiAPI;

$api = new PloiAPI();
$poller = new DeploymentLogPoller($api);
```

--------------------------------

### Get Site ID by Domain

Source: https://github.com/ploi/cli/blob/main/_autodocs/api-reference/Concerns.md

Resolves a domain name to a site ID, with fuzzy matching as a fallback. Use this when you need to find a site's ID based on its domain name, especially when the exact domain might not be known or there are typos.

```php
// Exact match
$siteId = $this->getSiteIdByDomain(1, 'example.com');

// Fuzzy match - prompts if exact not found
$siteId = $this->getSiteIdByDomain(1, 'examplee.com');  // Suggests: example.com
```

--------------------------------

### Configuration Constructor

Source: https://github.com/ploi/cli/blob/main/_autodocs/api-reference/Configuration.md

Initializes the Configuration service. It automatically reads all configured config files from the .ploi/ directory upon instantiation. If files are missing or unreadable, configuration defaults to empty arrays.

```APIDOC
## Configuration Constructor

### Description
Initializes the Configuration service by reading all configured config files from the `.ploi/` directory. If files don't exist or cannot be parsed, configuration defaults to empty arrays.

### Signature
```php
public function __construct()
```

### Properties
- `$configs` (array) - Associative array holding parsed configuration data (keys: 'settings', 'provision')
- `$configFiles` (array) - Mapping of config types to filenames (settings → settings.yml, provision → provision.yml)

### Example
```php
use App\Support\Configuration;

$config = new Configuration();
```
```

--------------------------------

### Make Generic API Request

Source: https://github.com/ploi/cli/blob/main/_autodocs/api-reference/PloiAPI.md

Illustrates how to perform generic HTTP requests to the Ploi API using various methods, including GET, POST, PATCH, and DELETE. It supports request data, pagination, and search parameters. The method handles common API errors by exiting with formatted messages.

```php
// GET request with pagination
$servers = $api->makeRequest('get', 'https://ploi.io/api/servers');

// POST request with data
$response = $api->makeRequest('post', 'https://ploi.io/api/servers', [
    'name' => 'production-server',
    'plan' => 'basic'
]);

// GET with search
$results = $api->makeRequest('get', 'https://ploi.io/api/servers', page: 1, search: 'prod');
```

--------------------------------

### Complete Interactive Command Flow

Source: https://github.com/ploi/cli/blob/main/_autodocs/api-reference/Concerns.md

Demonstrates a comprehensive interactive command flow, including server, site, and database selection. This pattern is useful for commands that require multiple user inputs or configuration settings.

```php
use App\Commands\Command;
use App\Commands\Concerns\InteractWithServer;
use App\Commands\Concerns\InteractWithSite;
use App\Commands\Concerns\InteractWithDatabase;
use App\Traits\EnsureHasToken;

class ManageCommand extends Command
{
    use EnsureHasToken,
        InteractWithServer,
        InteractWithSite,
        InteractWithDatabase;

    protected $signature = 'manage {--server=} {--site=} {--database=}';

    public function handle()
    {
        $this->ensureHasToken();

        // Option 1: Use configuration
        if ($this->hasPloiConfigurationFile() && !$this->option('server')) {
            $serverId = $this->configuration->get('settings.server');
            $siteId = $this->configuration->get('settings.site');
        }
        // Option 2: Use command options
        elseif ($this->option('server') && $this->option('site')) {
            $serverId = $this->getServerIdByNameOrIp($this->option('server'));
            $siteId = $this->getSiteIdByDomain($serverId, $this->option('site'));
        }
        // Option 3: Interactive selection
        else {
            [$serverId, $siteId] = $this->getServerAndSite();
        }

        // Select database
        $databaseId = $this->getDatabase();

        $this->info("Server: $serverId, Site: $siteId, Database: $databaseId");
    }
}
```

--------------------------------

### site:tenant:create

Source: https://github.com/ploi/cli/blob/main/_autodocs/commands.md

Creates a new tenant domain for a multi-tenant site.

```APIDOC
## site:tenant:create

### Description
Creates new tenant domain for multi-tenant site.

### Method
CLI Command

### Endpoint
site:tenant:create

### Parameters
#### Options
- `--server=ID` (string) - Required - Server ID or name
- `--site=DOMAIN` (string) - Required - Site domain
```

--------------------------------

### Deploy Site with Ploi CLI

Source: https://github.com/ploi/cli/blob/main/_autodocs/README.md

Deploy your site to staging with real-time log streaming, deploy to production, or schedule a deployment for a specific time.

```bash
# Deploy to staging (real-time log streaming)
./ploi deploy

# Deploy to production
./ploi deploy:production

# Schedule deployment
./ploi deploy --schedule="2024-12-25 14:30"
```

--------------------------------

### Use Initialized Settings for Deployment

Source: https://github.com/ploi/cli/blob/main/_autodocs/configuration.md

After initialization, subsequent commands like 'deploy' will automatically use the settings stored in .ploi/settings.yml.

```bash
./ploi deploy  # Uses .ploi/settings.yml
```

--------------------------------

### List Server Insights

Source: https://github.com/ploi/cli/blob/main/_autodocs/commands.md

Lists optimization and security recommendations for a server. Requires a server ID.

```bash
./ploi insights:list --server=ID
```

--------------------------------

### Daemon Configuration

Source: https://github.com/ploi/cli/blob/main/_autodocs/configuration.md

Configuration for setting up background processes (daemons), including the command, user, and working directory.

```php
[
    'command' => '/usr/bin/python3 app.py',
    'user' => 'ploi',
    'directory' => '/home/ploi/app',
]
```

--------------------------------

### Interactive Deployment

Source: https://github.com/ploi/cli/blob/main/_autodocs/commands.md

Executes a deployment command interactively, prompting for necessary information.

```bash
./ploi deploy
```

--------------------------------

### Deploy to Production

Source: https://github.com/ploi/cli/blob/main/_autodocs/api-reference/PloiAPI.md

Deploys a site from staging to the production environment. Requires server ID and site ID.

```APIDOC
## deployToProduction

### Description
Deploys a site to production.

### Method
POST

### Endpoint
/servers/{serverId}/sites/{siteId}/deploy/production

### Parameters
#### Path Parameters
- **serverId** (int) - Yes - Server ID
- **siteId** (int) - Yes - Site ID
```

--------------------------------

### Project Provisioning Configuration

Source: https://github.com/ploi/cli/blob/main/_autodocs/configuration.md

The `.ploi/provision.yml` file can store provisioning scripts, including shell commands and services to be configured. This is a work in progress.

```yaml
provision:
  commands:
    - "composer install"
    - "npm run build"
  services:
    - "nginx"
    - "php-fpm"
```

--------------------------------

### Instantiate PloiAPI

Source: https://github.com/ploi/cli/blob/main/_autodocs/api-reference/PloiAPI.md

Demonstrates how to create an instance of the PloiAPI class, either with an explicit API token or by using the token configured in `config('ploi.token')`.

```php
use App\Services\PloiAPI;

// Create with explicit token
$api = new PloiAPI('your-api-token');

// Create with token from config (default behavior)
$api = new PloiAPI();
```

--------------------------------

### Project Settings Configuration

Source: https://github.com/ploi/cli/blob/main/_autodocs/configuration.md

Project-level settings, including server, site, and domain, are stored in the `.ploi/settings.yml` file. This file is typically created by the `init` command.

```yaml
settings:
  server: "123"
  site: "456"
  domain: "example.com"
```

--------------------------------

### Accessing Command Options and Arguments

Source: https://github.com/ploi/cli/blob/main/_autodocs/api-reference/Command.md

Learn how to access arguments and options defined in your command's signature using the argument() and option() methods.

```php
class MyCommand extends Command
{
    protected $signature = 'my:command {name} {--force} {--output=}';

    public function handle()
    {
        // Arguments
        $name = $this->argument('name');  // Positional argument

        // Options
        $force = $this->option('force');   // Boolean option
        $output = $this->option('output'); // Option with value
    }
}
```

--------------------------------

### Interactive Server and Site Selection in PHP

Source: https://github.com/ploi/cli/blob/main/_autodocs/README.md

Utilize the `InteractWithServer` and `InteractWithSite` traits to easily retrieve server and site IDs through interactive prompts.

```php
use App\Commands\Concerns\InteractWithServer;
use App\Commands\Concerns\InteractWithSite;

class MyCommand extends Command
{
    use InteractWithServer, InteractWithSite;
    
    public function handle()
    {
        [$serverId, $siteId] = $this->getServerAndSite();
        // Use $serverId and $siteId
    }
}
```

--------------------------------

### Create New Server

Source: https://github.com/ploi/cli/blob/main/_autodocs/api-reference/PloiAPI.md

Initiates the creation of a new server on Ploi. Requires a data array containing server configuration details such as name, plan, region, and OS type.

```php
$newServer = $api->createServer([
    'name' => 'my-new-server',
    'plan' => 'small',
    'region' => 'us-east-1',
    'php_version' => '8.1',
    'webserver_type' => 'nginx'
]);
```

--------------------------------

### site:auth-user:create

Source: https://github.com/ploi/cli/blob/main/_autodocs/commands.md

Adds username/password basic authentication to a specified site.

```APIDOC
## site:auth-user:create

### Description
Adds username/password basic authentication to site.

### Method
CLI Command

### Endpoint
site:auth-user:create

### Parameters
#### Options
- `--server=ID` (string) - Required - Server ID or name
- `--site=DOMAIN` (string) - Required - Site domain
```

--------------------------------

### Combining Multiple Traits in a PHP Command

Source: https://github.com/ploi/cli/blob/main/_autodocs/api-reference/Traits.md

Demonstrates how to use the 'use' keyword to import and combine several traits into a single PHP class. This is useful for organizing and reusing common functionality across different commands.

```php
class CompleteCommand extends Command
{
    use EnsureHasToken,
        HasPloiConfiguration,
        HasRepo,
        InteractWithServer,
        InteractWithSite;

    public function handle()
    {
        // Validate authentication
        $this->ensureHasToken();

        // Get server and site
        if ($this->hasPloiConfigurationFile()) {
            $serverId = $this->configuration->get('settings.server');
            $siteId = $this->configuration->get('settings.site');
        } else {
            [$serverId, $siteId] = $this->getServerAndSite();
        }

        // Verify repository
        if (!$this->hasRepoInstalled($serverId, $siteId)) {
            $this->error('Repository not installed.');
            exit(1);
        }

        // Proceed...
    }
}
```

--------------------------------

### Server ID Decision Flow

Source: https://github.com/ploi/cli/blob/main/_autodocs/configuration.md

Illustrates the logic for determining the server ID, prioritizing command-line options, then configuration files, and finally falling back to interactive selection.

```php
public function getServerId()
{
    // Check for command option first
    if ($this->option('server')) {
        return $this->getServerIdByNameOrIp($this->option('server'));
    }

    // Use config file if present
    if ($this->hasPloiConfigurationFile()) {
        return $this->configuration->get('settings.server');
    }

    // Fall back to interactive selection
    return $this->getServerIdByNameOrIp($this->selectServer());
}
```

--------------------------------

### Configuration Methods

Source: https://github.com/ploi/cli/blob/main/_autodocs/README.md

The Configuration service manages project-level configuration files, supporting YAML parsing, dot notation access, and automatic directory creation for settings and provisioning.

```APIDOC
## Configuration

### Description
Manages project-level configuration files (`.ploi/settings.yml`, `.ploi/provision.yml`).

### Key Features
- YAML file parsing and generation
- Dot notation access to nested values
- Automatic directory creation

### Common Methods
- `get(string $key)` - Read configuration
- `set(string $key, $value)` - Write configuration
- `initialize(...)` - Create new project config
- `store(...)` - Persist to disk
```

--------------------------------

### Create Database User Configuration

Source: https://github.com/ploi/cli/blob/main/_autodocs/configuration.md

Configuration for creating a new database user with a specified password.

```php
[
    'name' => 'username',
    'password' => 'password',
]
```

--------------------------------

### Streaming Deployment Logs in PHP

Source: https://github.com/ploi/cli/blob/main/_autodocs/README.md

Use the `DeploymentLogPoller` service to stream deployment logs in real-time, processing each log line as it arrives.

```php
use App\Services\DeploymentLogPoller;

$poller = new DeploymentLogPoller($this->ploi);

$status = $poller->pollDeploymentLogs(
    $serverId,
    $siteId,
    fn($line) => $this->line($line)
);
```

--------------------------------

### Select Site by Domain

Source: https://github.com/ploi/cli/blob/main/_autodocs/configuration.md

The `--site` option allows you to specify a site by its domain name, overriding interactive selection or configuration settings.

```bash
./ploi deploy --site="example.com"
```

--------------------------------

### Server Management Commands

Source: https://github.com/ploi/cli/blob/main/_autodocs/README.md

Provides commands for managing servers, including listing, creating, restarting, deleting, and viewing logs.

```APIDOC
## Server Management Commands

### Description
Commands for managing servers.

### Commands
- `server:list` - List all servers
- `server:create` - Create new server
- `server:restart` - Restart server
- `server:delete` - Delete server
- `server:logs` - View server logs
```

--------------------------------

### Fuzzy Domain Matching in Site Commands

Source: https://github.com/ploi/cli/blob/main/_autodocs/api-reference/Traits.md

Handles site selection by first attempting an exact domain match and then falling back to fuzzy matching with suggestions if no exact match is found. This improves user experience by accommodating typos.

```php
use App\Commands\Command;
use App\Commands\Concerns\InteractWithSite;

class SiteInfoCommand extends Command
{
    use InteractWithSite;

    public function handle()
    {
        $sites = collect($this->ploi->getSiteList($serverId)['data']);
        $domains = $sites->pluck('domain')->toArray();

        $userDomain = $this->argument('domain');
        
        // Exact match
        $site = $sites->firstWhere('domain', $userDomain);
        
        if (!$site) {
            // Fuzzy match with suggestions
            $selectedDomain = $this->getDomainSuggestionsWithSelection(
                $userDomain,
                $domains
            );
            
            if ($selectedDomain) {
                $site = $sites->firstWhere('domain', $selectedDomain);
            } else {
                $this->error("Site not found.");
                exit(1);
            }
        }

        $this->info("Site: {$site['domain']}");
    }
}
```

--------------------------------

### Testing DeploymentLogPoller with Callback

Source: https://github.com/ploi/cli/blob/main/_autodocs/api-reference/DeploymentLogPoller.md

Demonstrates how to test the `pollDeploymentLogs` method by collecting log lines in an array using a closure callback and asserting the final status.

```php
$lines = [];
$status = $poller->pollDeploymentLogs(
    $serverId,
    $siteId,
    fn($line) => $lines[] = $line
);

// Assert on collected lines
$this->assertContains('Running migrations...', $lines);
$this->assertEqual('active', $status);
```

--------------------------------

### site:tenant:list

Source: https://github.com/ploi/cli/blob/main/_autodocs/commands.md

Lists all tenants for a multi-tenant site.

```APIDOC
## site:tenant:list

### Description
Lists all tenants for multi-tenant site.

### Method
CLI Command

### Endpoint
site:tenant:list

### Parameters
#### Options
- `--server=ID` (string) - Required - Server ID or name
- `--site=DOMAIN` (string) - Required - Site domain
```

--------------------------------

### Add Configuration File

Source: https://github.com/ploi/cli/blob/main/_autodocs/api-reference/Configuration.md

Adds a new configuration file type to be managed by the Configuration instance. The file is automatically loaded if it exists.

```php
$config = new Configuration();
$config->addConfigFile('deployment', 'deployment.yml');

// Now you can get/set deployment config:
$deployConfig = $config->get('deployment');
$config->set('deployment.strategy', 'rolling');
$config->store(getcwd() . '/.ploi/deployment.yml', 'deployment');
```

--------------------------------

### Schedule Deployment

Source: https://github.com/ploi/cli/blob/main/_autodocs/configuration.md

Schedule a deployment for a specific date and time using the --schedule option.

```bash
./ploi deploy --schedule="2024-12-25 14:30"
```

--------------------------------

### Use InteractWithServer Concern

Source: https://github.com/ploi/cli/blob/main/_autodocs/api-reference/Concerns.md

Demonstrates how to use the InteractWithServer concern to select a server within a custom command.

```php
use App\Commands\Concerns\InteractWithServer;

class MyCommand extends Command
{
    use InteractWithServer;

    public function handle()
    {
        $serverName = $this->selectServer();
        echo "Selected: $serverName";
    }
}
```

--------------------------------

### Integration with DeployCommand

Source: https://github.com/ploi/cli/blob/main/_autodocs/api-reference/DeploymentLogPoller.md

Shows how DeployCommand utilizes DeploymentLogPoller to stream real-time logs during a site deployment. A callback is provided to display logs with timestamps.

```php
use App\Services\DeploymentLogPoller;

class DeployCommand extends Command
{
    public function handle()
    {
        // Deploy
        $this->ploi->deploySite($serverId, $siteId, []);

        // Stream logs
        $poller = new DeploymentLogPoller($this->ploi);
        
        $status = $poller->pollDeploymentLogs($serverId, $siteId, function ($line) {
            $timestamp = now()->format('H:i:s');
            $this->line("<fg=gray>[{$timestamp}]</> {$line}");
        });

        // Handle result
        if ($status === 'active') {
            $this->success('Deployment successful!');
        } else {
            $this->error('Deployment failed.');
        }
    }
}
```

--------------------------------

### Manage Site Configuration with Ploi CLI

Source: https://github.com/ploi/cli/blob/main/_autodocs/README.md

Pull environment variables from the server, edit them, and push them back. Secure your site by adding an SSL certificate or a domain alias.

```bash
# Pull environment variables
./ploi site:env:pull

# Edit and push back
./ploi site:env:push

# Add SSL certificate
./ploi site:secure

# Add domain alias
./ploi site:alias:create
```

--------------------------------

### Working with Nested Configuration Arrays

Source: https://github.com/ploi/cli/blob/main/_autodocs/api-reference/Configuration.md

Shows how to use dot notation to read and set values within nested arrays in the configuration. Supports deep nesting via Laravel's Arr::set.

```php
$config = new Configuration();

// Read nested values
$commands = $config->get('provision.commands');      // array
$firstCommand = $config->get('provision.commands.0'); // string

// Set nested values
$config->set('provision.commands', ['npm install', 'npm run build']);
$config->set('provision.services', ['nginx', 'mysql']);

// Set deeply nested (uses Laravel's Arr::set)
$config->set('provision.commands.0', 'composer install');
```

--------------------------------

### createAuthUser

Source: https://github.com/ploi/cli/blob/main/_autodocs/api-reference/PloiAPI.md

Creates a new basic authentication user for a site on a server.

```APIDOC
## createAuthUser

### Description
Creates a basic auth user.

### Method
Not specified (assumed to be a client-side method call)

### Parameters
#### Path Parameters
- **serverId** (int) - Yes - Server ID
- **siteId** (int) - Yes - Site ID

#### Request Body
- **data** (array) - Yes - User data (username, password)
```

--------------------------------

### Accessing Configuration Values in PHP

Source: https://github.com/ploi/cli/blob/main/_autodocs/README.md

Retrieve server, site, and domain IDs from the configuration object within your commands.

```php
// In any command
$serverId = $this->configuration->get('settings.server');
$siteId = $this->configuration->get('settings.site');
$domain = $this->configuration->get('settings.domain');
```