--- title: "CLI reference" summary: "Every visible driga command and flag, generated from the same Kong command tree that prints `driga --help`." description: "Every driga command, subcommand, argument and flag, with defaults and allowed values." generated: true read_when: - "You need the exact spelling, default or allowed values of a driga flag." - "You are scripting driga and want to know which commands take --json or --yes." --- Watch AI coding agent sessions across your machines and projects. This page is generated from the command tree that `driga --help` prints, so it matches the binary built from the same commit. Run `driga --help` for the same text in a terminal. Running `driga` with no command runs `driga summary`. Exit codes: `0` success; `1` failure, refusal or partial completion; `2` invalid usage or missing required non-interactive input. A command that needs confirmation exits `2` when stdin is not a terminal unless `--yes` is passed. ## Global flags | Flag | Default | Description | |---|---|---| | `-h, --help` | | Show context-sensitive help. | | `--version` | | Print the driga version. | ## Commands | Command | Description | |---|---| | [`driga summary`](#driga-summary) | Show a one-screen summary. Bare driga opens top in a terminal. | | [`driga flow`](#driga-flow) | Show a session family and its state signals. | | [`driga agents`](#driga-agents) | List agents grouped by family. | | [`driga projects`](#driga-projects) | List project status. | | [`driga inbox`](#driga-inbox) | List attention and completion events. | | [`driga orphans`](#driga-orphans) | List orphan process trees. | | [`driga machines`](#driga-machines) | List known machines and their connection health. | | [`driga cleanup`](#driga-cleanup) | Inspect and explicitly clean local agent disk candidates. | | [`driga top`](#driga-top) | Open the interactive session viewer. | | [`driga web`](#driga-web) | Serve the interactive browser dashboard on loopback. | | [`driga ask`](#driga-ask) | Ask a one-shot Chat question through Claude and driga's read-only tools. | | [`driga mcp`](#driga-mcp) | Serve read-only MCP tools over stdio. | | [`driga doctor`](#driga-doctor) | Check setup and collection health. | | [`driga init`](#driga-init) | Guide optional setup. | | [`driga config`](#driga-config) | Inspect or edit configuration. | | [`driga collect`](#driga-collect) | Run the collector (what launchd runs). | | [`driga service`](#driga-service) | Manage the collector service. | | [`driga hooks`](#driga-hooks) | Manage agent hooks. | | [`driga fleet`](#driga-fleet) | Inspect fleet identity, serving status and viewers. | | [`driga version`](#driga-version) | Print the driga version. | ## driga summary Show a one-screen summary. Bare driga opens top in a terminal. ```sh driga summary [flags] ``` | Flag | Default | Description | |---|---|---| | `--machine=` | `all` | Scope to a machine name, ID, device-ID prefix, local, or all. | | `--project=` | | Scope to one project (path, name, or dot). | | `--since=` | | Only show items since a duration ago or yesterday. | | `--snapshot` | | Force one-shot snapshot collection without history. | | `--json` | | Print versioned JSON instead of tables. | | `--no-color` | | Disable colors. | ## driga flow Show a session family and its state signals. ```sh driga flow [] [flags] ``` | Argument | Default | Description | |---|---|---| | `[]` | | Internal session ID (defaults to most recently active live interactive session). | | Flag | Default | Description | |---|---|---| | `--machine=` | `all` | Scope to a machine name, ID, device-ID prefix, local, or all. | | `--project=` | | Scope to one project (path, name, or dot). | | `--since=` | | Only show items since a duration ago or yesterday. | | `--snapshot` | | Force one-shot snapshot collection without history. | | `--json` | | Print versioned JSON instead of tables. | | `--no-color` | | Disable colors. | | `--minutes=` | `60` | Time window: 15, 60 or 240 minutes. | ## driga agents List agents grouped by family. Without a subcommand, runs `driga agents list`. | Subcommand | Description | |---|---| | [`driga agents list`](#driga-agents-list) | List agents grouped by family. | | [`driga agents show`](#driga-agents-show) | Show one session by session ID. | | [`driga agents jump`](#driga-agents-jump) | Confirm and jump to a local session. | | [`driga agents kill`](#driga-agents-kill) | Confirm and terminate a local idle session. | ### driga agents list List agents grouped by family. ```sh driga agents list [flags] ``` | Flag | Default | Description | |---|---|---| | `--machine=` | `all` | Scope to a machine name, ID, device-ID prefix, local, or all. | | `--project=` | | Scope to one project (path, name, or dot). | | `--since=` | | Only show items since a duration ago or yesterday. | | `--snapshot` | | Force one-shot snapshot collection without history. | | `--json` | | Print versioned JSON instead of tables. | | `--no-color` | | Disable colors. | | `--all` | | Include sessions ended within the last 24 hours. | ### driga agents show Show one session by session ID. ```sh driga agents show [flags] ``` | Argument | Default | Description | |---|---|---| | `` | | Internal session ID. | | Flag | Default | Description | |---|---|---| | `--machine=` | `all` | Scope to a machine name, ID, device-ID prefix, local, or all. | | `--project=` | | Scope to one project (path, name, or dot). | | `--snapshot` | | Force one-shot snapshot collection without history. | | `--json` | | Print versioned JSON instead of tables. | | `--no-color` | | Disable colors. | ### driga agents jump Confirm and jump to a local session. ```sh driga agents jump [flags] ``` | Argument | Default | Description | |---|---|---| | `` | | Internal session ID. | | Flag | Default | Description | |---|---|---| | `-y, --yes` | | Jump without asking for confirmation. | ### driga agents kill Confirm and terminate a local idle session. ```sh driga agents kill [flags] ``` | Argument | Default | Description | |---|---|---| | `` | | Internal session ID. | | Flag | Default | Description | |---|---|---| | `--force` | | Escalate survivors to SIGKILL (TerminateProcess on Windows); use --yes to skip confirmation. | | `-y, --yes` | | Skip confirmation; identity and idle checks still apply. | ## driga projects List project status. Without a subcommand, runs `driga projects list`. | Subcommand | Description | |---|---| | [`driga projects list`](#driga-projects-list) | List project status. | | [`driga projects show`](#driga-projects-show) | Show project status, worktrees and sessions. | | [`driga projects summarize`](#driga-projects-summarize) | Refresh opt-in local project summaries through Claude. | ### driga projects list List project status. ```sh driga projects list [flags] ``` | Flag | Default | Description | |---|---|---| | `--machine=` | `all` | Scope to a machine name, ID, device-ID prefix, local, or all. | | `--project=` | | Scope to one project (path, name, or dot). | | `--since=` | | Only show items since a duration ago or yesterday. | | `--snapshot` | | Force one-shot snapshot collection without history. | | `--json` | | Print versioned JSON instead of tables. | | `--no-color` | | Disable colors. | | `--at-risk` | | Only show projects with risk flags. | | `--active` | | Only show active projects. | ### driga projects show Show project status, worktrees and sessions. ```sh driga projects show [flags] ``` | Argument | Default | Description | |---|---|---| | `` | | Repository name or path. | | Flag | Default | Description | |---|---|---| | `--machine=` | `all` | Scope to a machine name, ID, device-ID prefix, local, or all. | | `--snapshot` | | Force one-shot snapshot collection without history. | | `--json` | | Print versioned JSON instead of tables. | | `--no-color` | | Disable colors. | ### driga projects summarize Refresh opt-in local project summaries through Claude. ```sh driga projects summarize [...] [flags] ``` | Argument | Default | Description | |---|---|---| | `[ ...]` | | Local project names or paths; requires names or --all. | | Flag | Default | Description | |---|---|---| | `--json` | | Print versioned JSON instead of tables. | | `--all` | | Summarize every collected local project. | ## driga inbox List attention and completion events. Without a subcommand, runs `driga inbox list`. | Subcommand | Description | |---|---| | [`driga inbox list`](#driga-inbox-list) | List inbox events. | | [`driga inbox ack`](#driga-inbox-ack) | Explicitly acknowledge inbox events. | | [`driga inbox jump`](#driga-inbox-jump) | Jump to a local inbox item without acknowledging it. | ### driga inbox list List inbox events. ```sh driga inbox list [flags] ``` | Flag | Default | Description | |---|---|---| | `--machine=` | `all` | Scope to a machine name, ID, device-ID prefix, local, or all. | | `--project=` | | Scope to one project (path, name, or dot). | | `--since=` | | Only show items since a duration ago or yesterday. | | `--snapshot` | | Force one-shot snapshot collection without history. | | `--json` | | Print versioned JSON instead of tables. | | `--no-color` | | Disable colors. | | `--all` | | Show all history, including acknowledged and ended events (default: current waits and up to 50 completions from 24h). | ### driga inbox ack Explicitly acknowledge inbox events. ```sh driga inbox ack [] [flags] ``` | Argument | Default | Description | |---|---|---| | `[]` | | Inbox item ID. | | Flag | Default | Description | |---|---|---| | `--machine=` | `all` | Scope to a machine name, ID, device-ID prefix, local, or all. | | `--all` | | Acknowledge every unacknowledged item. | ### driga inbox jump Jump to a local inbox item without acknowledging it. ```sh driga inbox jump ``` | Argument | Default | Description | |---|---|---| | `` | | Inbox item ID. | ## driga orphans List orphan process trees. Without a subcommand, runs `driga orphans list`. | Subcommand | Description | |---|---| | [`driga orphans list`](#driga-orphans-list) | List orphan candidates. | | [`driga orphans kill`](#driga-orphans-kill) | Confirm and terminate an orphan tree. | ### driga orphans list List orphan candidates. ```sh driga orphans list [flags] ``` | Flag | Default | Description | |---|---|---| | `--project=` | | Scope candidates to one project (path, name, or dot). | | `--machine=` | `all` | Scope to a machine name, ID, device-ID prefix, local, or all. | | `--since=` | | Only show items since a duration ago or yesterday. | | `--snapshot` | | Force one-shot snapshot collection without history. | | `--json` | | Print versioned JSON instead of tables. | | `--no-color` | | Disable colors. | ### driga orphans kill Confirm and terminate an orphan tree. ```sh driga orphans kill [] [flags] ``` | Argument | Default | Description | |---|---|---| | `[]` | | Orphan candidate ID. | | Flag | Default | Description | |---|---|---| | `--machine=` | `all` | Select orphan candidates from this machine, local, or all. | | `--snapshot` | | Collect one snapshot before selecting candidates. | | `-y, --yes` | | Skip confirmation; identity and idle checks still apply. | | `--all` | | Select all local orphan candidates; verify and confirm each unless --yes. | | `--force` | | Escalate survivors to SIGKILL (TerminateProcess on Windows); confirmation is still required unless --yes. | ## driga machines List known machines and their connection health. Without a subcommand, runs `driga machines list`. | Subcommand | Description | |---|---| | [`driga machines list`](#driga-machines-list) | List known machines and connection health. | | [`driga machines show`](#driga-machines-show) | Show one machine (default: local). | | [`driga machines reset-id`](#driga-machines-reset-id) | Regenerate the local machine identity. | ### driga machines list List known machines and connection health. ```sh driga machines list [flags] ``` | Flag | Default | Description | |---|---|---| | `--machine=` | `all` | Scope to a machine name, ID, device-ID prefix, local, or all. | | `--snapshot` | | Force one-shot snapshot collection without history. | | `--json` | | Print versioned JSON instead of tables. | | `--no-color` | | Disable colors. | ### driga machines show Show one machine (default: local). ```sh driga machines show [] [flags] ``` | Argument | Default | Description | |---|---|---| | `[]` | `local` | Machine name, ID, device-ID prefix, or local. | | Flag | Default | Description | |---|---|---| | `--project=` | | Scope process detail to one project (path, name, or dot). | | `--snapshot` | | Force one-shot snapshot collection without history. | | `--json` | | Print versioned JSON instead of tables. | | `--no-color` | | Disable colors. | | `--full` | | Show all retained MCP trends and full process detail. | ### driga machines reset-id Regenerate the local machine identity. ```sh driga machines reset-id [flags] ``` | Flag | Default | Description | |---|---|---| | `-y, --yes` | | Apply without asking for confirmation. | ## driga cleanup Inspect and explicitly clean local agent disk candidates. Without a subcommand, runs `driga cleanup list`. | Subcommand | Description | |---|---| | [`driga cleanup list`](#driga-cleanup-list) | List local disk cleanup candidates. | | [`driga cleanup remove`](#driga-cleanup-remove) | Verify and remove selected local disk candidates. | ### driga cleanup list List local disk cleanup candidates. ```sh driga cleanup list [flags] ``` | Flag | Default | Description | |---|---|---| | `--json` | | Print versioned JSON instead of tables. | | `--kind=` | | Filter by worktree, scratch, or history. | | `--sizes` | | Walk candidate sizes on demand. | | `--why` | | Include worktrees that do not qualify, with reasons. | ### driga cleanup remove Verify and remove selected local disk candidates. ```sh driga cleanup remove [] [flags] ``` | Argument | Default | Description | |---|---|---| | `[]` | | Candidate ID to clean after confirmation. | | Flag | Default | Description | |---|---|---| | `--json` | | Print versioned JSON instead of tables. | | `--kind=` | | Filter by worktree or scratch (required with --all); history is report-only. | | `--sizes` | | Walk candidate sizes on demand (30s cap per walk). | | `--all` | | Remove ready candidates of --kind; skip candidates needing review and report failures. | | `--dry-run` | | Print exact commands after verification without removing anything. | | `-y, --yes` | | Confirm the displayed action without prompting. | | `--include-ignored` | | Allow listed non-regenerable ignored files for one explicit ID. | ## driga top Open the interactive session viewer. ```sh driga top [flags] ``` | Flag | Default | Description | |---|---|---| | `--machine=` | `all` | Scope to a machine name, ID, device-ID prefix, local, or all. | | `--project=` | | Scope to one project (path, name, or dot). | | `--since=` | | Only show items since a duration ago or yesterday. | | `--snapshot` | | Force one-shot snapshot collection without history. | | `--no-color` | | Disable colors. | | `--theme=` | | TUI theme: system, light or dark (overrides ui.theme). | | `--tab=` | `flow` | Initial tab: flow, projects or machines. | ## driga web Serve the interactive browser dashboard on loopback. ```sh driga web [flags] ``` | Flag | Default | Description | |---|---|---| | `--machine=` | `all` | Scope to a machine name, ID, device-ID prefix, local, or all. | | `--project=` | | Scope to one project (path, name, or dot). | | `--since=` | | Only show items since a duration ago or yesterday. | | `--snapshot` | | Force one-shot snapshot collection without history. | | `--listen=` | `127.0.0.1:0` | Loopback address and port for the dashboard. | | `--open` | | Open the dashboard in your browser. | ## driga ask Ask a one-shot Chat question through Claude and driga's read-only tools. ```sh driga ask ... [flags] ``` | Argument | Default | Description | |---|---|---| | ` ...` | | One-shot Chat question using Claude and driga's read-only tools. | | Flag | Default | Description | |---|---|---| | `--machine=` | `all` | Scope to a machine name, ID, device-ID prefix, local, or all. | | `--project=` | | Scope to one project (path, name, or dot). | | `--json` | | Print versioned JSON instead of tables. | ## driga mcp Serve read-only MCP tools over stdio. ```text Read-only MCP server on stdio. Reading never acknowledges inbox items; snapshot mode has no history. Claude Code: claude mcp add --scope user driga -- driga mcp Codex configuration: [mcp_servers.driga] command = "driga" args = ["mcp"] ``` ```sh driga mcp [flags] ``` | Flag | Default | Description | |---|---|---| | `--snapshot` | | Force one-shot snapshot collection for read tools (no history). | ## driga doctor Check setup and collection health. ```sh driga doctor [flags] ``` | Flag | Default | Description | |---|---|---| | `--json` | | Print versioned JSON instead of tables. | ## driga init Guide optional setup. ```sh driga init [flags] ``` | Flag | Default | Description | |---|---|---| | `-y, --yes` | | Accept each optional setup change without asking. | ## driga config Inspect or edit configuration. | Subcommand | Description | |---|---| | [`driga config path`](#driga-config-path) | Print the config path. | | [`driga config show`](#driga-config-show) | Print effective values including defaults. | | [`driga config edit`](#driga-config-edit) | Edit the config with $EDITOR (default vi). | ### driga config path Print the config path. ```sh driga config path [flags] ``` | Flag | Default | Description | |---|---|---| | `--json` | | Print versioned JSON instead of tables. | ### driga config show Print effective values including defaults. ```sh driga config show ``` ### driga config edit Edit the config with $EDITOR (default vi). ```sh driga config edit ``` ## driga collect Run the collector (what launchd runs). ```sh driga collect [flags] ``` | Flag | Default | Description | |---|---|---| | `--serve` | | Enable fleet serving alongside collection (overrides fleet.serve). | | `--listen=` | | Fleet private IP or interface and port (requires serving). | | `--once` | | Collect once into the persistent database and exit. | | `--cpu-profile=` | | Write a CPU profile of the collector to this file. | | `--profile-for=` | `2m` | How long --cpu-profile records before it stops. | ## driga service Manage the collector service. | Subcommand | Description | |---|---| | [`driga service install`](#driga-service-install) | Install and start the collector service. | | [`driga service start`](#driga-service-start) | Start the collector service. | | [`driga service stop`](#driga-service-stop) | Stop the collector service. | | [`driga service restart`](#driga-service-restart) | Restart the collector service. | | [`driga service status`](#driga-service-status) | Show collector service status. | | [`driga service logs`](#driga-service-logs) | Print collector logs. | | [`driga service uninstall`](#driga-service-uninstall) | Uninstall the collector service. | ### driga service install Install and start the collector service. ```sh driga service install ``` ### driga service start Start the collector service. ```sh driga service start ``` ### driga service stop Stop the collector service. ```sh driga service stop ``` ### driga service restart Restart the collector service. ```sh driga service restart ``` ### driga service status Show collector service status. ```sh driga service status ``` ### driga service logs Print collector logs. ```sh driga service logs [flags] ``` | Flag | Default | Description | |---|---|---| | `-f, --follow` | | Follow collector log output. | ### driga service uninstall Uninstall the collector service. ```sh driga service uninstall ``` ## driga hooks Manage agent hooks. | Subcommand | Description | |---|---| | [`driga hooks install`](#driga-hooks-install) | Preview and install agent hooks. | | [`driga hooks uninstall`](#driga-hooks-uninstall) | Preview and remove Driga's agent hooks. | | [`driga hooks status`](#driga-hooks-status) | Show installed agent hooks. | ### driga hooks install Preview and install agent hooks. ```sh driga hooks install [] [flags] ``` | Argument | Default | Description | |---|---|---| | `[]` | `all` | Adapter: claude, codex, copilot, or all. | | Flag | Default | Description | |---|---|---| | `--dry-run` | | Print the diff without writing or prompting. | | `-y, --yes` | | Apply without asking for confirmation. | | `--otlp` | | Configure optional metadata-only loopback OTLP instead of hooks. | | `--traces` | | Include Claude beta spans (requires --otlp). | ### driga hooks uninstall Preview and remove Driga's agent hooks. ```sh driga hooks uninstall [] [flags] ``` | Argument | Default | Description | |---|---|---| | `[]` | `all` | Adapter: claude, codex, copilot, or all. | | Flag | Default | Description | |---|---|---| | `--dry-run` | | Print the diff without writing or prompting. | | `-y, --yes` | | Apply without asking for confirmation. | | `--otlp` | | Configure optional metadata-only loopback OTLP instead of hooks. | | `--traces` | | Include Claude beta spans (requires --otlp). | ### driga hooks status Show installed agent hooks. ```sh driga hooks status [] [flags] ``` | Argument | Default | Description | |---|---|---| | `[]` | `all` | Adapter: claude, codex, copilot, or all. | | Flag | Default | Description | |---|---|---| | `--otlp` | | Show optional loopback OTLP status. | ## driga fleet Inspect fleet identity, serving status and viewers. | Subcommand | Description | |---|---| | [`driga fleet peers`](#driga-fleet-peers) | List paired machines. | | [`driga fleet viewers`](#driga-fleet-viewers) | List identities trusted to read this machine. | | [`driga fleet enroll`](#driga-fleet-enroll) | Open a bounded pairing window. | | [`driga fleet rekey`](#driga-fleet-rekey) | Regenerate identity; invalidate all pairings. | | [`driga fleet id`](#driga-fleet-id) | Print this machine's fleet device ID. | | [`driga fleet status`](#driga-fleet-status) | Show the serving collector's live state. | ### driga fleet peers List paired machines. | Subcommand | Description | |---|---| | [`driga fleet peers list`](#driga-fleet-peers-list) | List paired machines. | | [`driga fleet peers add`](#driga-fleet-peers-add) | Pair with a serving machine. | | [`driga fleet peers remove`](#driga-fleet-peers-remove) | Remove a peer locally. | #### driga fleet peers list List paired machines. ```sh driga fleet peers list [flags] ``` | Flag | Default | Description | |---|---|---| | `--json` | | Print versioned JSON instead of tables. | #### driga fleet peers add Pair with a serving machine. ```sh driga fleet peers add [flags] ``` | Argument | Default | Description | |---|---|---| | `` | | Peer host[:port] (default port 7411). | | Flag | Default | Description | |---|---|---| | `-y, --yes` | | Skip confirmation only with --device-id identity pinning. | | `--json` | | Print versioned JSON instead of tables. | | `--name=` | | Local name for the peer. | | `--device-id=` | | Require this peer device ID (headless). | #### driga fleet peers remove Remove a peer locally. ```sh driga fleet peers remove [flags] ``` | Argument | Default | Description | |---|---|---| | `` | | Peer name, device ID or machine ID (removed peers with --purge). | | Flag | Default | Description | |---|---|---| | `-y, --yes` | | Apply without asking for confirmation. | | `--purge` | | Delete this peer's cached rows. | ### driga fleet viewers List identities trusted to read this machine. | Subcommand | Description | |---|---| | [`driga fleet viewers list`](#driga-fleet-viewers-list) | List identities trusted to read this machine. | | [`driga fleet viewers revoke`](#driga-fleet-viewers-revoke) | Revoke a viewer immediately. | #### driga fleet viewers list List identities trusted to read this machine. ```sh driga fleet viewers list [flags] ``` | Flag | Default | Description | |---|---|---| | `--json` | | Print versioned JSON instead of tables. | #### driga fleet viewers revoke Revoke a viewer immediately. ```sh driga fleet viewers revoke [flags] ``` | Argument | Default | Description | |---|---|---| | `` | | Viewer name or device ID. | | Flag | Default | Description | |---|---|---| | `-y, --yes` | | Apply without asking for confirmation. | ### driga fleet enroll Open a bounded pairing window. ```sh driga fleet enroll [flags] ``` | Flag | Default | Description | |---|---|---| | `-y, --yes` | | Skip confirmation only with --allow-viewer identity pinning. | | `--allow-ack` | | Allow this viewer to acknowledge inbox items. | | `--allow-viewer=` | | Pre-authorize exactly this viewer device ID (headless). | | `--window=` | | Enrollment duration (default fleet.enroll_window, at most 10m). | ### driga fleet rekey Regenerate identity; invalidate all pairings. ```sh driga fleet rekey [flags] ``` | Flag | Default | Description | |---|---|---| | `-y, --yes` | | Apply without asking for confirmation. | ### driga fleet id Print this machine's fleet device ID. ```sh driga fleet id [flags] ``` | Flag | Default | Description | |---|---|---| | `--json` | | Print versioned JSON instead of tables. | ### driga fleet status Show the serving collector's live state. ```sh driga fleet status [flags] ``` | Flag | Default | Description | |---|---|---| | `--json` | | Print versioned JSON instead of tables. | ## driga version Print the driga version. ```sh driga version [flags] ``` | Flag | Default | Description | |---|---|---| | `--json` | | Print versioned JSON instead of tables. |