This document describes the homeboy.json module manifest format used by the Homeboy CLI and (via the CLI) the desktop app.

Overview

Modules extend Homeboy with custom functionality. Each module is a self-contained directory with:

• homeboy.json – Manifest file (required)
• Optional scripts (executed by the CLI based on runtime.* commands)
• Optional assets and configuration

Installation location

Homeboy Desktop is macOS-only.

The desktop app stores installed modules under its AppPaths root:

• Desktop config root (single source of truth: AppPaths):

  ~/Library/Application Support/Homeboy/
  

• Modules:

  ~/Library/Application Support/Homeboy/modules/<module-id>/
  

Homeboy Desktop installs/links modules by running the CLI (homeboy module install ...), but the desktop app does not assume it shares the same on-disk config root as the CLI (dirs::config_dir()/homeboy).

Note: the CLI embeds its core documentation in the binary (see homeboy docs).

Module responsibilities

Homeboy modules can:

• define project type behavior for the platform (discovery, CLI templates, DB templates, deploy verification, version parsing patterns, etc.)
• define executable tools (optional runtime.* section) runnable via homeboy module run

The manifest is a single unified homeboy.json file; modules include only fields they need.

For the authoritative runtime behavior, see homeboy/docs/commands/module.md.

Manifest Schema

Root Object

Runtime Object

Executable modules use the CLI runtime contract described in homeboy/docs/commands/module.md.

The manifest’s runtime object configures shell commands that the CLI runs (for example runCommand, setupCommand, and optional readyCheck). The CLI injects execution context and merged settings via environment variables.

Requirements Object

Modules can declare dependencies on project configuration (components, feature flags, and project type). Modules with unmet requirements appear disabled in the sidebar.

Input Object

Output Object

Schema Object

Action Object

Builtin Actions

API Actions

Template Variables:

• {{selected}} – Array of selected result rows
• {{settings.key}} – Value from module settings

Setting Object

Module output

For homeboy module run, the CLI streams the module process output to the console and determines success/failure based on exit code.

If your module is intended for use in Homeboy Desktop’s dynamic UI, structure your module homeboy.json using the inputs/output/actions/settings fields documented in this file.

Examples

Desktop-focused module (dynamic UI)

{
  "id": "example-tool",
  "name": "Example Tool",
  "version": "1.0.0",
  "icon": "hammer",
  "description": "Example module demonstrating inputs/output/actions",
  "author": "Your Name",

  "inputs": [
    {
      "id": "url",
      "type": "text",
      "label": "URL",
      "placeholder": "https://example.com",
      "arg": "--url"
    }
  ],

  "output": {
    "schema": {
      "type": "array",
      "items": {
        "title": "string",
        "link": "string"
      }
    },
    "display": "table",
    "selectable": true
  },

  "actions": [
    {
      "id": "copy-links",
      "label": "Copy Links",
      "type": "builtin",
      "builtin": "copy-column",
      "column": "link"
    }
  ],

  "settings": []
}

Project configuration

Project configuration requirements (local environment settings, subtargets, and CLI template variables) are defined by the CLI and the active project type.

Use the CLI as the source of truth:

• homeboy docs project
• homeboy docs module