# 🚀 DiskTracker CLI Subcommand Reference Card

This reference card details every subcommand, parameter, flag, and usage example in DiskTracker.

---

## 1. Core Daemon Lifecycle Management

### `disktracker init`
Starts or registers the DiskTracker background daemon as a Windows Service and initiates baseline scanning.
* **Usage**: `disktracker init`
* **Admin privileges required**: Yes.

### `disktracker status`
Queries the running background daemon's state and monitored volumes.
* **Usage**: `disktracker status`
* **Parameters**: 
  * `--json`: Returns raw JSON (useful for tooling/scripts) instead of human-readable text.

### `disktracker doctor`
Runs health diagnostics on the local installation, including checks for Admin permissions, NTFS Journal access, SQLite integrity, and database WAL-mode config.
* **Usage**: `disktracker doctor`
* **Admin privileges required**: Yes.

### `disktracker uninstall`
Stops the running daemon, terminates the service registry, removes the named pipe, and cleans up database files.
* **Usage**: `disktracker uninstall [flags]`
* **Admin privileges required**: Yes.
* **Flags**:
  * `--delete-snapshot`: Deletes all historical snapshot index files as well (default keeping snapshots).
  * `-y`, `--yes`: Auto-approves the confirmation prompt.

---

## 2. Windows Service Control

### `disktracker service <subcommand>`
Direct Win32 service wrapper operations.
* **Admin privileges required**: Yes.
* **Subcommands**:
  * `register`: Registers DiskTracker as a Windows Service named `DiskTracker`.
  * `unregister`: Stops and unregisters the `DiskTracker` service.
  * `start`: Starts the registered Windows Service.
  * `stop`: Stops the registered Windows Service.

---

## 3. Database Search and Statistics

### `disktracker search [query]`
Performs ultra-fast substring searches on indexed filenames. By default, it runs an exact case-insensitive substring search.
* **Usage**: `disktracker search "log" [options]`
* **Options**:
  * `--advanced` (alias `--advance`): Enable multi-tier scoring (phrase, prefix, ngram, fuzzy matching).
  * `--fuzzy`: Enable fuzzy matching scoring tier.
  * `--path <path>`: Filter files by folder path prefix (e.g. `C:\Users`).
  * `--ext <extension>`: Filter by exact file extension (e.g. `pdf`).
  * `--volume <volume>`: Filter by volume designation (e.g. `C:`).
  * `--min-size <bytes>`: Filter files larger than `N` bytes.
  * `--max-size <bytes>`: Filter files smaller than `N` bytes.
  * `--modified-after <duration/datetime>`: Filter files modified after a relative duration (e.g., `2d`, `12h`) or absolute UTC datetime (RFC3339).
  * `--modified-before <duration/datetime>`: Filter files modified before a relative duration or UTC datetime.
  * `--hidden`: Filter hidden files.
  * `--system`: Filter system files.
  * `--limit <limit>`: Maximum results to return (default: `100`).
  * `--json`: Outputs raw JSON results.

### `disktracker history [path]`
Displays the mutation timeline of a folder or file.
* **Display rules**: Created/Deleted/Renamed always shown (including 0B). Modified only when `|size_delta| >= 2`. Consecutive identical Created/Deleted/Renamed rows for the same file are aggregated; Modified rows stay unique.
* **Usage**: `disktracker history [path] [options]`
* **Options**:
  * `--since <duration/datetime>`: Filter events after a relative time (e.g., `2d`, `12h`) or UTC datetime.
  * `--until <duration/datetime>`: Filter events before a relative time or UTC datetime.
  * `--kind <Created/Modified/Deleted/Renamed>`: Filter by change action.
  * `--collapse`: Also merges consecutive same-file same-kind rows (including Modified size deltas). Identical Created/Deleted/Renamed rows are already aggregated without this flag.
  * `--limit <limit>`: Max entries to return (default: `100`).
  * `--json`: Outputs raw JSON results.

### `disktracker top`
Ranks files and directories by size, growth, or modifications.
* **Display rules** (growth mode): 0B create/delete events can appear; tiny non-zero growth under 2B is hidden.
* **Usage**: `disktracker top [options]`
* **Options**:
  * `--path <path>`: Restricts ranking to a specific folder path.
  * `--volume <volume>`: Restricts ranking to a specific volume (e.g. `C:`).
  * `--folders`: Group results by folder rollup sizes (conflicts with `--files`).
  * `--files`: Flat listing of largest files (conflicts with `--folders`).
  * `--since <duration/datetime>`: Filter growth or churn since a relative duration.
  * `--between <SNAP_A> <SNAP_B>`: Compare growth/churn delta between two snapshots.
  * `--growth`: Rank results by size delta (default for interval mode).
  * `--churn`: Rank results by modification frequency.
  * `--limit <limit>`: Max items to display (default: `20`).

---

## 4. Snapshot Management

### `disktracker snapshot <subcommand>`
Manage and inspect volume snapshots.
* **Subcommands**:
  * `create [--label <name>] [path]`: Takes a snapshot index of the specified volume or folder with a custom label (auto-generated if omitted).
  * `list [--volume <vol>]`: Lists all saved snapshots in the system.
  * `diff <snapshot_a> <snapshot_b> [--path <prefix>]`: Computes the net mutations and size differences between two snapshots. Created/Deleted/Renamed always shown (including 0B); Modified only when `|size_delta| >= 2`.

---

## 5. Conversational AI Agent

### `disktracker ai <subcommand>`
Configure the AI model bindings.
* **Subcommands**:
  * `config [options]`:
    * `--base-url <url>`: Set the LLM endpoint base URL.
    * `--api-key <token>`: Commit the LLM API token to the Windows Credential Manager.
    * `--model <name>`: Define the chat model name (e.g., `gpt-4o`, `meta-llama/llama-3-70b`).
    * `--chat-session-store <true/false>`: Choose whether to save AI conversation histories.
    * `--websearch-provider <name>`: Configure web search provider (e.g. duckduckgo, google).
    * `--websearch-key <key>`: Commit the Web Search API key to Credential Manager.
  * `test`: Runs a structural ping handshake test with the configured LLM API.
  * `session <list/show>`: Manages saved conversation session history.

### `disktracker ask "<question>"`
Invokes the LangGraph agent to inspect the disk state using natural language.
* **Usage**: `disktracker ask "Which folders in my AppData grew the most yesterday?"`
* **Options**:
  * `-i`, `--interactive`: Enable interactive Action mode. Allows the AI agent to propose file system mutations (like deleting caches or temporary log files) under human-in-the-loop (HITL) approval gates.
  * `--session <id>`: Resume a previous conversation session.

---

## 6. Self-Update Utility

### `disktracker update`
Checks the GitHub repository for the latest release, downloads the appropriate target archive, stops any running background daemons/services, performs a zero-downtime binary swap, restarts the daemon, and cleans up old temporary binaries.
* **Usage**: `disktracker update`
* **Admin privileges required**: Yes (on Windows if installed in program files or registered as a Windows Service).