Configuration

Config file location

CMDHub stores everything in:

~/.cmdhub/config.json

The file is created automatically on first launch with permissions 0600 (readable only by your user). You normally interact with it through the CMDHub UI - changes are saved immediately whenever you modify a project or service.

File structure

{
  "globalProxySettings": {
    "enabled": true,
    "tld": "test"
  },
  "projects": [
    {
      "id": "abc123",
      "name": "My App",
      "rootDirectory": "/Users/you/projects/myapp",
      "icon": "app.badge",
      "domain": "myapp",
      "services": [
        {
          "id": "svc1",
          "name": "Frontend",
          "command": "npm run dev",
          "workingDirectory": "",
          "port": 3000,
          "subdomain": "frontend",
          "envFile": ".env.local",
          "env": {
            "NODE_ENV": "development"
          },
          "dependencies": [],
          "healthCheck": {
            "type": "http",
            "target": "http://localhost:3000",
            "interval": 5,
            "timeout": 3
          }
        }
      ]
    }
  ]
}

Top-level keys

Key	Description
`globalProxySettings`	Reverse proxy and DNS settings shared across all projects
`projects`	Array of project objects

Project fields

Field	Description
`id`	Auto-generated UUID
`name`	Display name
`rootDirectory`	Absolute path to the project root
`icon`	SF Symbol name for the menu bar icon
`domain`	Base domain used by the reverse proxy (e.g., `myapp` → `*.myapp.test`)
`services`	Array of service objects

Service fields

Field	Description
`command`	Shell command to run
`workingDirectory`	Relative to `rootDirectory` if not absolute; defaults to root
`port`	Port the service listens on (used by proxy)
`subdomain`	Subdomain prefix for the reverse proxy
`envFile`	Path to a `.env` file (relative to `rootDirectory`)
`env`	Inline key-value environment variables
`dependencies`	Array of service IDs that must be running first
`healthCheck`	Health check configuration (see Health Checks)

Environment variables

Each service gets environment variables from two sources, merged in this order (later wins):

.env file - path set in envFile, resolved relative to the project root
Inline env - key-value pairs defined directly in the service config

Example:

"envFile": ".env.local",
"env": {
  "PORT": "3000",
  "API_URL": "http://localhost:4000"
}

Shell RC sourcing

CMDHub launches services through a login shell so that tools installed via Homebrew, nvm, rbenv, and other managers are on $PATH. It sources your shell profile (~/.zshrc, ~/.bash_profile, etc.) before running each service command.

If a command works in your terminal but not in CMDHub, check that the tool is available in a login shell:

/bin/zsh -l -c 'which your-command'

Versioning your config

Because config.json is a plain JSON file in your home directory, you can back it up or track it in a dotfiles repo:

cp ~/.cmdhub/config.json ~/dotfiles/cmdhub-config.json

Project-specific settings (commands, ports, env var keys) are good candidates for version control. Avoid committing values that contain secrets.