# CLI Mode

Kudu can run entirely from the command line — no GUI window is opened. This is useful for scripting, IT admin workflows, and scheduled tasks beyond the built-in scheduler.

## Usage

```
kudu --cli [options] [categories...]
```

## Categories

| Flag | Description |
|------|-------------|
| `--system` | System temp files, caches, logs, crash dumps |
| `--browser` | Browser caches (Chrome, Edge, Brave, Firefox, etc.) |
| `--app` | Application caches (Discord, VS Code, npm, etc.) |
| `--gaming` | Game launcher caches, GPU shader caches, redistributables |
| `--recycle-bin` | Windows Recycle Bin |
| `--all` | All categories (default when none specified) |

## Options

| Flag | Description |
|------|-------------|
| `--clean` | Delete found items after scanning (without this flag, scan-only) |
| `--json` | Output results as JSON instead of human-readable text |
| `--verbose` | Show detailed progress, timing, and debug info |
| `-q`, `--quiet` | Suppress all output except errors and final result |
| `-h`, `--help` | Show help message |
| `-v`, `--version` | Show version |

`--verbose` and `--quiet` are mutually exclusive.

## Examples

```bash
# Scan everything (dry run — nothing is deleted)
kudu --cli

# Scan and clean system junk only
kudu --cli --system --clean

# Scan system and browser caches
kudu --cli --system --browser

# Scan everything and clean, output as JSON (for scripting)
kudu --cli --all --clean --json

# Use in a scheduled task (Task Scheduler, cron, etc.)
kudu --cli --all --clean
```

## JSON Output

When `--json` is passed, output is a single JSON object:

```json
{
  "scan": {
    "categories": ["system", "browser"],
    "results": [
      {
        "category": "system",
        "subcategory": "User Temp Files",
        "itemCount": 42,
        "totalSize": 104857600,
        "items": [{ "path": "...", "size": 1024, "lastModified": 1700000000000 }]
      }
    ],
    "totalItems": 42,
    "totalSize": 104857600
  },
  "clean": {
    "totalCleaned": 104857600,
    "filesDeleted": 40,
    "filesSkipped": 2,
    "errors": []
  }
}
```

The `clean` key is only present when `--clean` is used.

With `--json`, stdout carries nothing but the JSON document — progress lines and verbose
diagnostics are written to stderr instead, so output can be piped straight into a parser:

```bash
kudu --cli programs list --json | jq '.count'   # stdout is pure JSON
kudu --cli programs list --json 2>/dev/null     # discard progress entirely
```

## Repair (Windows)

```bash
kudu --cli repair gpu-restart             # soft-restart display adapters (admin required)
kudu --cli repair winre-status            # Enabled / Disabled / Unknown (admin required)
kudu --cli repair winre-status --verbose  # include location + BCD id
kudu --cli repair winre-status --json
```

`gpu-restart` uses Disable/Enable-PnpDevice on class `Display` — not key injection of Win+Ctrl+Shift+B.

## Prometheus Metrics

Print metrics in Prometheus text format (useful for `node_exporter` textfile collector):

```bash
kudu --cli metrics
kudu --cli metrics --json    # JSON array of metric objects
```

Start a persistent HTTP metrics server:

```bash
kudu --cli metrics-server              # default port 9100
kudu --cli metrics-server --port 9200  # custom port
# Endpoints: /metrics (Prometheus), /health (JSON)
```

## Exit Codes

| Code | Meaning |
|------|---------|
| `0` | Success |
| `1` | General error |
| `2` | Invalid arguments |
| `3` | Permission denied (needs elevation) |
| `4` | Partial success (some operations failed) |
| `5` | Nothing found (scan returned zero items) |
| `6` | Unknown command |
| `7` | Threats/issues found requiring attention |

## Uninstall leftovers (Windows)

`kudu --cli leftovers scan --json` reports old cache/log folders belonging to applications that Kudu previously observed installed. Kudu records the installed-program inventory locally when this command runs. The first scan establishes that inventory; it does not classify unknown folders as abandoned applications. Applications removed before Kudu observed them are not eligible.

A later scan requires the owner to be absent from the current registry inventory and its recorded install location to be gone. Matching installed folders and running processes protect application data. Results include only explicit cache/log children older than 30 days, never entire application profiles, install directories, known save-game locations, uninstall metadata, or anti-cheat runtimes. Recognizable save files, recent contents, links, inaccessible contents, and trees exceeding the inspection bounds are excluded. Inventory failures abort the scan.

Review the returned paths, then explicitly select each folder to clean:

```powershell
kudu --cli leftovers scan --json
kudu --cli leftovers clean --path "C:\Users\YourName\AppData\Local\OldApp\Cache" --json
```

Repeat `--path` to select multiple folders. Bare `leftovers clean`, `--all`, wildcards, and paths absent from the fresh scan are rejected with exit code 2. Cleanup caches the selected scan IDs before deletion and returns the standard failure/partial-success exit codes if deletion fails. A prior scan's IDs are not valid across CLI processes; select by the exact reviewed paths instead.