Synopsis

homeboy project [OPTIONS] <COMMAND>

Common Workflows

Linking Components to a Project

After creating components, link them to a project:

# Add components to existing project
homeboy project components add my-project component-1 component-2

# Or set all components at once (replaces existing)
homeboy project components set my-project component-1 component-2

Components must exist (created via homeboy component create) before linking.

Subcommands

list

homeboy project list

show

homeboy project show <project_id>

Arguments:

• <project_id>: project ID

create

homeboy project create [OPTIONS] [<id>] [<domain>]

create supports two modes:

• CLI mode: pass [<id>] [<domain>] as positional arguments.
• JSON mode: pass --json <spec> (CLI mode arguments are not required).

Options:

• --json <spec>: JSON input spec for create/update (single object or bulk; see below)
• --skip-existing: skip items that already exist (JSON mode only)
• --server-id <server_id>: optional server ID
• --base-path <path>: optional base path (local or remote depending on server configuration)
• --table-prefix <prefix>: optional table prefix (only used by extensions that care about table naming)

Arguments (CLI mode):

• [<id>]: project ID
• [<domain>]: public site domain

JSON mode:

• <spec> accepts - (stdin), @file.json, or an inline JSON string.
• The payload is the project object (single or array for bulk).

Single:

{ "id": "my-project", "domain": "example.com" }

Bulk:

[
  { "id": "my-project", "domain": "example.com" },
  { "id": "my-project-2", "domain": "example.com" }
]

JSON output:

Note: all command output is wrapped in the global JSON envelope described in the JSON output contract. The object below is the data payload.

Note: all command output is wrapped in the global JSON envelope described in the JSON output contract. The object below is the data payload.

{
  "command": "project.create",
  "project_id": "<project_id>",
  "project": { }
}

Note: all command output is wrapped in the global JSON envelope described in the JSON output contract. The object below is the data payload.

{
  "command": "project.create",
  "import": {
    "results": [{ "id": "<project_id>", "action": "created|updated|skipped|error" }],
    "created": 1,
    "updated": 0,
    "skipped": 0,
    "errors": 0
  }
}

Local Projects

CLI mode:

Creating a Local Project

homeboy project create <id> <domain> --base-path <local-path>

JSON mode:

homeboy project create my-site my-site.local 
    --base-path "/path/to/site/public"

What Works Locally

Projects without a --server-id execute commands locally instead of via SSH. Homeboy is environment-agnostic – it works the same way regardless of whether your local environment uses Docker, native installs, or any other setup.

• CLI tools (homeboy wp, homeboy composer) – execute in local shell
• Database (homeboy db) – uses extension templates, executes locally
• Logs (homeboy logs) – reads files from base_path
• Files (homeboy file) – browses/edits files at base_path
• Extension platform behaviors – project discovery, version patterns, etc.

What Requires a Server

Example:

• homeboy deploy – uploads artifacts to remote server
• homeboy db tunnel – creates SSH tunnel for database access

Subcommands (continued)

set

homeboy project set <project_id> --json <JSON>
homeboy project set <project_id> '<JSON>'
homeboy project set --json <JSON>   # project_id may be provided in JSON body

All commands execute locally when no server_id is configured:

Only these commands require server_id:

• --json <JSON>: JSON object to merge into config (supports @file and - for stdin)
• --replace <field>: replace array fields instead of union (repeatable)

Updates a project by merging a JSON object into projects/<id>.json.

• set no longer supports individual field flags; use --json and provide the fields you want to update.
• Use null in JSON to clear a field (for example, {"component_ids": null}).

Options:

Note: all command output is wrapped in the global JSON envelope described in the JSON output contract. The object below is the data payload.

{
  "command": "project.set",
  "project_id": "<project_id>",
  "project": { },
  "updated": ["domain", "server_id"],
  "import": null
}

Notes:

Note: all command output is wrapped in the global JSON envelope described in the JSON output contract. The object below is the data payload.

{
  "command": "project.list",
  "projects": [
    {
      "id": "<project_id>",
      "domain": "<domain>"
    }
  ]
}

Note: all command output is wrapped in the global JSON envelope described in the JSON output contract. The object below is the data payload.

Note: all command output is wrapped in the global JSON envelope described in the JSON output contract. The object below is the data payload.

{
  "command": "project.show",
  "project_id": "<project_id>",
  "project": { },
  "import": null
}

JSON output:

components

homeboy project components <COMMAND>

Note: all command output is wrapped in the global JSON envelope described in the JSON output contract. The object below is the data payload.

components list

homeboy project components list <project_id>

Note: all command output is wrapped in the global JSON envelope described in the JSON output contract. The object below is the data payload.

Note: all command output is wrapped in the global JSON envelope described in the JSON output contract. The object below is the data payload.

{
  "command": "project.components.list",
  "project_id": "<project_id>",
  "components": {
    "action": "list",
    "project_id": "<project_id>",
    "component_ids": ["<component_id>", "<component_id>"],
    "components": [ { } ]
  }
}

components add

homeboy project components add <project_id> <component_id> [<component_id>...]

JSON output (list):

components remove

homeboy project components remove <project_id> <component_id> [<component_id>...]

Note: all command output is wrapped in the global JSON envelope described in the JSON output contract. The object below is the data payload.

components clear

homeboy project components clear <project_id>

JSON output (show):

components set

homeboy project components set <project_id> <component_id> [<component_id>...]

Note: all command output is wrapped in the global JSON envelope described in the JSON output contract. The object below is the data payload.

project is the serialized ProjectRecord ({ id, config }).

homeboy project set <project_id> --json '{"component_ids":["chubes-theme","chubes-blocks"]}'

Manage the list of components associated with a project.

homeboy project components set chubes chubes-theme chubes-blocks chubes-contact chubes-docs chubes-games

Lists component IDs and the resolved component configs.

{
  "command": "project.components.set",
  "project_id": "<project_id>",
  "components": {
    "action": "set",
    "project_id": "<project_id>",
    "component_ids": ["<component_id>", "<component_id>"],
    "components": [ { } ]
  },
  "updated": ["component_ids"]
}

pin

homeboy project pin <COMMAND>

pin list

homeboy project pin list <project_id> --type <file|log>

JSON output:

{
  "command": "project.pin.list",
  "project_id": "<project_id>",
  "pin": {
    "action": "list",
    "project_id": "<project_id>",
    "type": "file|log",
    "items": [
      {
        "path": "<path>",
        "label": "<label>|null",
        "display_name": "<display-name>",
        "tail_lines": 100
      }
    ]
  }
}

pin add

homeboy project pin add <project_id> <path> --type <file|log> [--label <label>] [--tail <lines>]

Adds components to the project if they are not already present.

{
  "command": "project.pin.add",
  "project_id": "<project_id>",
  "pin": {
    "action": "add",
    "project_id": "<project_id>",
    "type": "file|log",
    "added": { "path": "<path>", "type": "file|log" }
  }
}

pin remove

homeboy project pin remove <project_id> <path> --type <file|log>

Removes components from the project. Errors if any provided component ID is not currently attached.

{
  "command": "project.pin.remove",
  "project_id": "<project_id>",
  "pin": {
    "action": "remove",
    "project_id": "<project_id>",
    "type": "file|log",
    "removed": { "path": "<path>", "type": "file|log" }
  }
}

rename

homeboy project rename <project_id> <new_id>

Removes all components from the project.

Replaces the full component_ids list on the project (deduped, order-preserving). Component IDs must exist in homeboy component list.

• new_id is lowercased before writing.
• The project is moved from projects/<old-id>.json to projects/<new-id>.json.
• Component references are updated automatically.

You can also do this via project set by merging component_ids:

homeboy project rename my-project my-new-project

Example:

{
  "command": "project.rename",
  "project_id": "<project_id>",
  "new_id": "<new_id>",
  "renamed": true
}

remove

homeboy project remove <project_id> --json '<JSON>'
homeboy project remove <project_id> '<JSON>'

JSON output:

JSON output:

• --json <JSON>: JSON object to remove from config (supports @file and - for stdin)

JSON output:

JSON output:

# Remove a component
homeboy project remove my-project --json '{"component_ids": ["component-id"]}'

Renames a project by changing its ID.

{
  "command": "project.remove",
  "project_id": "<project_id>",
  "removed": ["component_ids"],
  "project": {}
}

Related

• JSON output contract