CLI Commands

GUI-first

groove is designed as a GUI-first tool. The dashboard at localhost:31415 is the primary interface for spawning, monitoring, and managing agents. The CLI exists for power users, scripting, and quick access from the terminal.

groove start

Start the groove daemon.

groove start
groove start --host tailscale    # bind to Tailscale IP
groove start --host 192.168.1.5  # bind to specific IP

Flag	Description	Default
--port	Port to run on	31415
--host	Host/IP to bind to (tailscale for auto-detect)	127.0.0.1

Launches the daemon and serves the GUI. Auto-detects your environment (VS Code, SSH, local) and prints the right instructions. On first run, triggers the setup wizard to detect installed providers.

groove stop

Stop the daemon.

groove stop

groove spawn

Spawn a new agent.

groove spawn --role <role> [--scope <glob>] [--model <model>]

Flag	Description	Default
--role	Agent role (e.g., backend, frontend, database)	Required
--scope	File glob for ownership (e.g., "src/api/**")	None
--model	Lock to a specific model	Auto-routed

groove kill

Kill an agent.

groove kill <agent-id>

groove agents

List all active agents.

groove agents

groove status

Show daemon status, active agents, and session stats.

groove status

groove nuke

Emergency stop -- kill all agents and stop the daemon.

groove nuke

groove rotate

Trigger context rotation for a specific agent. Kills the agent, generates a handoff brief, and respawns with fresh context.

groove rotate <agent-id>

groove providers

List available AI providers and their installation status.

groove providers

Example output:

  Provider       Status      Models
  claude-code    installed   claude-opus-4-6, claude-sonnet-4-6, claude-haiku-4-5
  codex          installed   o3, o4-mini
  gemini         not found   -
  ollama         installed   llama3, codellama

groove set-key

Set an API key for a provider. The key is encrypted with AES-256-GCM and stored locally.

groove set-key <provider> <key>

groove set-key codex sk-your-openai-key
groove set-key gemini AIza-your-google-key

groove config show

Display the current configuration.

groove config show

groove config set

Set a configuration value.

groove config set <key> <value>

groove config set defaultProvider claude-code
groove config set maxAgents 8
groove config set rotationThreshold 0.7

groove team save

Save current agent configuration as a team.

groove team save <name>

groove team load

Load a saved team configuration and spawn all agents.

groove team load <name>

groove team list

List saved teams.

groove team list

groove team delete

Delete a saved team.

groove team delete <name>

groove team export

Export a team configuration as a JSON file.

groove team export <name>

groove team import

Import a team from a JSON file.

groove team import <file>

groove approvals

List pending approval requests in the queue.

groove approvals

groove approve

Approve a pending request.

groove approve <approval-id>

groove reject

Reject a pending request.

groove reject <approval-id>

groove connect

Connect to a remote groove daemon via SSH tunnel.

groove connect user@host
groove connect my-vps                          # SSH config alias
groove connect -i ~/.ssh/key.pem user@host     # explicit key

Flag	Description
-i, --identity <keyfile>	SSH private key file
--no-browser	Don't open the browser automatically

Creates an encrypted SSH tunnel and opens the remote GUI in your browser. The tunnel runs in the background until you disconnect.

groove disconnect

Close the SSH tunnel to a remote daemon.

groove disconnect

groove audit

View the audit log of state-changing operations.

groove audit
groove audit -n 50     # show last 50 entries

Flag	Description	Default
-n, --limit <count>	Number of entries to show	25

groove federation pair

Pair with a remote groove daemon for cross-server coordination.

groove federation pair <host>
groove federation pair 100.64.1.5
groove federation pair 100.64.1.5:31415

Exchanges Ed25519 public keys with the remote daemon. Both sides store each other as trusted peers.

groove federation unpair

Remove a paired peer.

groove federation unpair <peer-id>

groove federation list

List all paired peers.

groove federation list

groove federation status

Show federation status — daemon ID, keypair, and paired peers.

groove federation status