# CLI & Dashboard Guide

`beautyspot` は、キャッシュされたデータの閲覧や、ディスク容量を管理するためのコマンドラインツールを提供しています。

## Dashboard (UI)

キャッシュされたタスクの実行履歴、結果、依存関係などをブラウザで視覚的に確認できます。

### Basic Usage

```bash
beautyspot ui <path_to_db>

```

* **`<path_to_db>`**: Spotを作成した際に指定したデータベースファイルのパス（デフォルトでは `.beautyspot/project_name.db` など）。

---

## メンテナンスとクリーンアップ

タスクを実行し続けると、キャッシュデータベースやストレージ容量が増加していきます。`beautyspot` はこれらを管理するために、目的別の3つのコマンドを提供しています。

### コマンドの役割分担

| コマンド | アプローチ | 対象 | 目的 | 推奨頻度 |
| --- | --- | --- | --- | --- |
| **`gc`** | **宣言的 (Declarative)** | 全体 | **ポリシー執行**（期限切れデータの削除）とゴミ掃除 | 定期実行 (Daily) |
| **`prune`** | **命令的 (Imperative)** | タスク | **手動介入**（「30日以上前のデータ」を一括削除） | 必要に応じて |
| **`clean`** | **修復 (Repair)** | ファイル | **整合性回復**（DBにない孤立ファイルの削除） | トラブル時のみ |

### 1. ガベージコレクション (`gc`)

`gc` は、**日常的なメンテナンス**で使用するメインコマンドです。
ワークスペース内の全てのデータベースをスキャンし、事前に定義されたルール（Lifecycle Policy）に従って不要なデータを削除します。

**主な機能:**

1. **期限切れタスクの削除**: `@mark(retention="7d")` などで設定された期限を過ぎたデータを、全てのデータベースから削除します（デフォルト有効）。
2. **ゾンビプロジェクトの削除**: `.db` ファイルが削除され、取り残されたストレージディレクトリを削除します。

**使用例:**

```bash
# 全てのプロジェクトをスキャンし、期限切れデータとゾンビプロジェクトを削除
$ beautyspot gc

# 期限切れタスクの削除は行わず、ゾンビプロジェクトの削除のみ行う
$ beautyspot gc --no-expired

# 実際に削除せず、何が消えるか確認する
$ beautyspot gc --dry-run

```

**推奨:** `cron` 等で定期実行することで、宣言した保持期間（Retention）に従ってディスク容量が自動的に管理されます。

### 2. 古いタスクの手動削除 (`prune`)

`prune` は、ポリシーに関係なく、**「古いデータを一括で消したい」** 場合に使用します。ディスク容量が逼迫した場合の緊急対応などに適しています。

**例:** 最終更新から30日以上経過したタスクを無条件で削除する

```bash
$ beautyspot prune .beautyspot/project.db --days 30

```

* **動作:** 指定された日数より古いレコードを削除し、関連するBlobファイルも削除します。

!!! note "関数名フィルタについて"
    `--func` などの関数名フィルタは、**完全修飾名（`module.qualname`）を優先**してマッチします。
    同名関数がある場合は完全修飾名を指定してください。短い関数名も後方互換のため引き続き使えます。
    具体例は Usage Patterns の「Function Identity」セクションを参照してください: `docs/guides/usage_patterns.md`。

### 3. 孤立ファイルのクリーンアップ (`clean`)

`clean` は、**ストレージの整合性を修復** するための低レイヤーコマンドです。
通常、`gc` や `prune` が自動的に整合性を保つため、頻繁に使う必要はありません。プロセスのクラッシュなどで「DBレコードは消えたが、ファイルだけ残っている」状態が発生した場合に使用します。

**例:**

```bash
$ beautyspot clean .beautyspot/project.db

```
