Synopsis

homeboy project [OPTIONS] <COMMAND>

Common Workflows

Linking Components to a Project

After creating a repo-owned component config, attach that checkout to a project:

homeboy project components attach-path my-project /path/to/component-repo

# Or replace all component attachments at once
homeboy project components set my-project --json '[{"id":"component-1","local_path":"/repo/component-1","remote_path":"wp-content/plugins/component-1"}]'

attach-path discovers the component from the checkout’s homeboy.json and adds a project attachment for that repo path.

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.

• Extension CLI tools (homeboy wp, homeboy cargo, or extension-provided verbs) – 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> --base64 <BASE64_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)
• --base64 <BASE64_JSON>: Base64-encoded JSON object for shell-sensitive payloads
• --replace <field>: replace array fields instead of union (repeatable)

Updates a project by merging a JSON object into projects/<id>.json. Arbitrary project updates must use --json or --base64; positional JSON and positional key=value updates are not accepted.

• 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, {"server_id": 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 attach-path

homeboy project components attach-path <project_id> <local_path>

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> --json '<attachments-json>'

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 '{"components":[{"id":"chubes-theme","local_path":"/repo/chubes-theme","remote_path":"wp-content/themes/chubes-theme"}]}'

Manage the list of components associated with a project.

homeboy project components set chubes --json '[{"id":"chubes-theme","local_path":"/repo/chubes-theme","remote_path":"wp-content/themes/chubes-theme"}]'

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": ["components"]
}

delete

homeboy project delete <project_id>

JSON output:

init

homeboy project init <project_id>

Attaches a repo path for a project component discovered via that repo’s homeboy.json.

status

homeboy project status <project_id>
homeboy project status <project_id> --health-only

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

pin

homeboy project pin <COMMAND>

pin list

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

Removes all components from the project.

{
  "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>]

Replaces the full component attachment list on the project. The JSON payload is an array of attachments with fields such as id, local_path, and remote_path.

{
  "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>

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

{
  "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>

Example:

JSON output:

• 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.

Deletes a project configuration.

homeboy project rename my-project my-new-project

Initializes the configured project directory.

{
  "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>'

Shows live server health and component versions for a project. Use --health-only to skip component version checks.

JSON output:

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

JSON output:

JSON output:

# Remove a shared table entry
homeboy project remove my-project --json '{"shared_tables": ["wp_users"]}'

Renames a project by changing its ID.

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

Related

• JSON output contract