Configuration

Grove stores its configuration in ~/.config/grove/.

Files

CLI Configuration

The CLI configuration file at ~/.config/grove/cli.json stores persistent settings.

{
  "port": 3000
}

Options

The port can also be set per-invocation with the --port flag, which takes precedence and updates the saved config.

Sessions

Active terminal sessions are tracked in ~/.config/grove/sessions.json. This file is managed automatically — sessions are added when created and removed when cleaned up.

Each session entry contains:

• Session ID
• Repository name and branch
• Working directory
• Terminal URL and port
• ttyd process PID
• The command being run (for grove run sessions)

Environment Variables

You can configure environment variables for each repository through the Mac app or by editing ~/.config/grove/config.json directly.

Environment variables are defined per repository:

{
  "repos": [
    {
      "id": "abc12345",
      "path": "/Users/you/Projects/my-app",
      "name": "my-app",
      "envVars": [
        {
          "key": "DATABASE_URL",
          "value": "postgresql://localhost:5432/mydb",
          "filePath": ".env.local"
        },
        {
          "key": "API_KEY",
          "value": "your-api-key-here"
        }
      ]
    }
  ]
}

Fields

When a worktree is created, Grove generates the environment files with the configured variables.

Setup Steps

Setup steps are commands that run automatically when a session starts. There are two ways to configure them:

1. .grove/setup.json — Committed to your repository. Shared with your team.
2. Config UI — Managed through the Grove Mac app. Stored in ~/.config/grove/config.json.

If both are present, .grove/setup.json takes full priority — config.json steps are ignored.

.grove/setup.json (recommended)

Create .grove/setup.json in your repository root:

{
  "setup": [
    {
      "name": "Install dependencies",
      "run": "npm install"
    },
    {
      "name": "Build project",
      "run": "npm run build"
    }
  ]
}

This file can be committed to version control so all team members get the same setup steps.

Config UI

You can also manage setup steps per-repository through the Grove Mac app or by editing ~/.config/grove/config.json directly. Steps are stored under each repo entry:

{
  "repos": [
    {
      "id": "abc12345",
      "path": "/Users/you/Projects/my-app",
      "name": "my-app",
      "setupSteps": [
        {
          "name": "Install dependencies",
          "run": "npm install"
        }
      ]
    }
  ]
}

The Mac app provides a JSON view of your configured steps that you can copy and paste into a .grove/setup.json file when you're ready to commit them.

Fields

Behavior

• Steps run sequentially in the worktree directory
• Each step streams output in real-time to the UI
• Each step shows status: pending, running, done, failed, or stopped
• If a step fails, subsequent steps are skipped
• You can cancel running steps or retry failed ones from the UI
• Output from each step is viewable in the setup inspector
• Background steps start but don't block — the runner immediately moves to the next step. This is useful for long-running processes like dev servers that never exit on their own. Background steps can be individually stopped and restarted from the UI.

Priority

Example for React Native / Expo

{
  "setup": [
    {
      "name": "Install dependencies",
      "run": "npm install"
    },
    {
      "name": "Install pods",
      "run": "cd ios && pod install"
    },
    {
      "name": "Build iOS",
      "run": "npx expo run:ios"
    }
  ]
}

Example with background steps

For monorepo setups where you need multiple dev servers running concurrently:

{
  "setup": [
    {
      "name": "Install dependencies",
      "run": "bun install"
    },
    {
      "name": "Web server",
      "run": "bun run web",
      "background": true
    },
    {
      "name": "React Native server",
      "run": "bun run native",
      "background": true
    }
  ]
}

TLS Certificates

Grove uses Tailscale certificates for HTTPS terminal access. Certificates are generated automatically using tailscale cert and stored in ~/.config/grove/certs/. They are reused across sessions for the same Tailscale hostname.