# `homeboy fleet`

Manage fleets — named groups of projects for coordinated operations across multiple sites.

## Synopsis

```sh
homeboy fleet <COMMAND>
```

## Overview

Fleets enable cloud version management by grouping projects that share components. Use fleets to:

- Deploy updates to multiple sites simultaneously
- Check version drift across your network
- Coordinate deployments between staging/production environments
- Keep shared plugins/themes in sync across a WordPress multisite network

**Hierarchy:**
- **Component** → versioned thing (plugin, CLI tool, extension)
- **Project** → deployment target (site on a server)
- **Fleet** → named group of projects

## Subcommands

### `create`

```sh
homeboy fleet create <id> [--projects <p1,p2,...>] [--description <text>]
```

Create a new fleet. Projects can be added at creation or later with `fleet add`.

### `show`

```sh
homeboy fleet show <id>
```

Display fleet configuration including project list.

### `set`

```sh
homeboy fleet set <id> --json <JSON>
homeboy fleet set <id> '<JSON>'
```

Update fleet configuration by merging a JSON object.

### `delete`

```sh
homeboy fleet delete <id>
```

Delete a fleet. Does not affect the projects themselves.

### `list`

```sh
homeboy fleet list
```

List all configured fleets.

### `add`

```sh
homeboy fleet add <id> --project <project_id>
homeboy fleet add <id> -p <project_id>
```

Add a project to a fleet. The project must exist.

### `remove`

```sh
homeboy fleet remove <id> --project <project_id>
homeboy fleet remove <id> -p <project_id>
```

Remove a project from a fleet. Does not delete the project.

### `projects`

```sh
homeboy fleet projects <id>
```

List all projects in a fleet with their full configuration.

### `components`

```sh
homeboy fleet components <id>
```

Show component usage across the fleet. Returns a map of component_id → [project_ids].

Useful for understanding which components are shared and where they're deployed.

### `status`

```sh
homeboy fleet status <id>
```

Show component versions for each project in the fleet. Reads local configuration only (no SSH).

Use `fleet check` for drift detection that compares local vs remote versions.

### `check`

```sh
homeboy fleet check <id> [--outdated]
```

Check component drift across the fleet by comparing local and remote versions via SSH.

Uses existing `deploy --check` infrastructure with version_targets pattern matching.

Options:
- `--outdated`: Only show components that need updates (filters out up_to_date)

Returns per-project status with:
- `local_version`: Version from local component files
- `remote_version`: Version fetched from remote server via SSH
- `status`: `up_to_date`, `needs_update`, or `unknown`

Summary includes counts for quick overview.

### `sync` (deprecated)

> **Deprecated.** Use `homeboy deploy` to sync files across servers instead. Register shared configs as components and deploy them like any other component. See [#101](https://github.com/Extra-Chill/homeboy/issues/101).

```sh
# Instead of: homeboy fleet sync fleet-servers
# Use:
homeboy deploy my-config --fleet fleet-servers
```

## Fleet Deployment

Fleets integrate with the deploy command:

```sh
# Deploy component to all projects in a fleet
homeboy deploy my-plugin --fleet production

# Deploy component to ALL projects using it (auto-detected)
homeboy deploy my-plugin --shared
```

See [deploy](deploy.md) for full deployment options.

## Shared Component Detection

To see which components are shared across projects:

```sh
homeboy component shared
# → my-plugin: [site-a, site-b, site-c]
# → homeboy: [project-1, project-2]

homeboy component shared my-plugin
# → [site-a, site-b, site-c]
```

## Example Workflow

```sh
# 1. See what's shared
homeboy component shared

# 2. Create a fleet
homeboy fleet create production --projects site-a,site-b,site-c

# 3. Check for drift
homeboy fleet check production
# → Shows local vs remote versions, identifies outdated components

# 4. Deploy updates
homeboy deploy my-plugin --fleet production
# → Deploys to all projects in fleet

# Or deploy to all users of a component
homeboy deploy my-plugin --shared
# → Auto-detects projects using my-plugin
```

## JSON Output

Top-level fields:

- `command`: action identifier (e.g., `fleet.create`, `fleet.check`)
- `fleet_id`: fleet ID for single-fleet actions
- `fleet`: fleet configuration
- `fleets`: list for `list` command
- `projects`: project details for `projects` command
- `components`: component usage map for `components` command
- `status`: version info per project for `status` command
- `check`: drift detection results for `check` command
- `summary`: aggregate counts for `check` command

Check result fields:
- `project_id`, `server_id`, `status`, `error`
- `components[]`: array with `component_id`, `local_version`, `remote_version`, `status`

Summary fields:
- `total_projects`, `projects_checked`, `projects_failed`
- `components_up_to_date`, `components_needs_update`, `components_unknown`

Sync result fields:
- `leader_project_id`: source of truth server
- `dry_run`: whether this was a preview run
- `projects[]`: per-project results with `project_id`, `server_id`, `status`, `error`
- `projects[].categories[]`: per-category results with `category`, `status`, `error`, `files_synced`
- `summary`: `total_projects`, `projects_synced`, `projects_failed`, `projects_skipped`, `total_categories`, `categories_synced`, `categories_failed`

## Related

- [deploy](deploy.md) — `--fleet` and `--shared` flags
- [component](component.md) — `component shared` command
- [server](server.md) — SSH connection configuration
- [project](project.md) — Project configuration
