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

Launches the daemon on port 31415. Serves the GUI and exposes the REST/WebSocket API. 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   -
  aider          installed   (any)
  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 set-key aider sk-your-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>