active: true
derived: false
groups:
- CLI
header: |
  CLIコマンド
level: 2.21
links:
- ARCH011: MuEszjxI2CEtYDj9vnuASs-Y55-4Zf45GBu_6uBGI-I=
normative: true
ref: ''
reviewed: LjwVvBZ6dXMXzvZYpV7lyDkvuesIlWnVeNjEP5KhBUI=
text: |
  ## インターフェース

  ```bash
  beautyspot list [--db DB_PATH]
  beautyspot gc [--name PROJECT_NAME] [--force]
  beautyspot stats
  beautyspot ui
  ```

  ## 振る舞い

  1. **コンテキスト解決**: `--db` 指定がない場合、デフォルトの `.beautyspot/` ディレクトリを探索する
  2. **コマンド実行**: `MaintenanceService` または `Spot` インスタンスを生成し、対応するメソッドを呼び出す
  3. **フォーマット出力**: `Rich` ライブラリを使用して、結果をテーブルやプログレスバーで表示する

  ## サブコマンド詳細

  | コマンド | 説明 |
  |---|---|
  | `list` | 保存されているキャッシュキーと関数名の一覧を表示 |
  | `gc` | 期限切れタスクと孤立Blobのクリーンアップを実行 |
  | `stats` | キャッシュヒット率やストレージ使用量の統計を表示 |
  | `ui` | ターミナルベースのインタラクティブダッシュボードを起動 |

  ## エラーハンドリング

  - **DB不在**: 指定されたパスにDBがない場合は、エラーメッセージを表示して終了する。
  - **権限不足**: ファイル削除権限がない場合は、スキップされた旨を表示する。

  ## エッジケース

  - **非対話環境**: CI等での実行を考慮し、色の無効化や確認プロンプトのスキップ（`--force`）に対応する。
