Manage global Homeboy configuration stored under the OS config directory as ~/.config/homeboy/homeboy.json.

Overview

The homeboy config command provides access to global configuration that controls default behaviors across all Homeboy operations. If no homeboy.json file exists, built-in defaults are used automatically.

Subcommands

homeboy config show

Display the current configuration (merged built-in defaults + file overrides).

homeboy config show              # Show merged config
homeboy config show --builtin    # Show only built-in defaults

homeboy config set

Set a configuration value at a JSON pointer path. Creates homeboy.json if it doesn’t exist.

homeboy config set <pointer> <value>

Examples:

# Remove legacy SCP protocol flag
homeboy config set /defaults/deploy/scp_flags '[]'

# Add a custom version file pattern
homeboy config set /defaults/version_candidates/4 '{"file": "VERSION", "pattern": "(\d+\.\d+\.\d+)"}'

# Change local file permissions
homeboy config set /defaults/permissions/local/file_mode 'g+r'

homeboy config remove

Remove a configuration value at a JSON pointer path.

homeboy config remove <pointer>

Example:

# Remove a custom version candidate
homeboy config remove /defaults/version_candidates/4

homeboy config reset

Delete homeboy.json and restore to built-in defaults.

homeboy config reset

homeboy config path

Show the path to homeboy.json and whether it exists.

homeboy config path

Configuration Schema

{
  "defaults": {
    "install_methods": {
      "homebrew": {
        "path_patterns": ["/Cellar/", "/homebrew/"],
        "upgrade_command": "brew update && brew upgrade homeboy",
        "list_command": "brew list homeboy"
      },
      "cargo": {
        "path_patterns": ["/.cargo/bin/"],
        "upgrade_command": "cargo install homeboy"
      },
      "source": {
        "path_patterns": ["/target/release/", "/target/debug/"],
        "upgrade_command": "git pull && cargo build --release"
      }
    },
    "version_candidates": [
      { "file": "Cargo.toml", "pattern": "version\s*=\s*"(\d+\.\d+\.\d+)"" },
      { "file": "package.json", "pattern": ""version"\s*:\s*"(\d+\.\d+\.\d+)"" },
      { "file": "composer.json", "pattern": ""version"\s*:\s*"(\d+\.\d+\.\d+)"" },
      { "file": "style.css", "pattern": "Version:\s*(\d+\.\d+\.\d+)" }
    ],
    "deploy": {
      "scp_flags": ["-O"],
      "artifact_prefix": ".homeboy-",
      "default_ssh_port": 22
    },
    "permissions": {
      "local": {
        "file_mode": "g+rw",
        "dir_mode": "g+rwx"
      },
      "remote": {
        "file_mode": "g+w",
        "dir_mode": "g+w"
      }
    }
  }
}

Configurable Behaviors

Install Methods

Controls how Homeboy detects installation method and upgrades itself:

• path_patterns: Strings to match in the executable path
• upgrade_command: Shell command to run for upgrades
• list_command: Optional command to verify installation (Homebrew only)

Version Candidates

List of files and regex patterns for auto-detecting version files:

• file: Filename to look for (e.g., Cargo.toml)
• pattern: Regex with capture group for version string

Deploy Settings

• scp_flags: Flags passed to SCP (default: ["-O"] for legacy protocol compatibility)
• artifact_prefix: Prefix for temporary deployment artifacts (default: .homeboy-)
• default_ssh_port: Default SSH port (default: 22)

Permissions

File permission modes applied during build and deploy:

• local.file_mode: chmod mode for local files before build
• local.dir_mode: chmod mode for local directories before build
• remote.file_mode: chmod mode for deployed files
• remote.dir_mode: chmod mode for deployed directories

JSON Output

All subcommands return JSON in the standard envelope format:

{
  "success": true,
  "data": {
    "command": "config.show",
    "config": { ... }
  }
}

Related

• upgrade – Uses install_methods configuration
• version – Uses version_candidates configuration
• deploy – Uses deploy and permissions configuration