> For the complete documentation index, see [llms.txt](https://getsquish.gitbook.io/squish/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://getsquish.gitbook.io/squish/ja/rifarensu/cli.md).

# CLI

```
squish <video> [--density 3x3|4x4|5x5|6x6] [--start <t>] [--end <t>] [--out <dir>] [--json]
squish mcp                 MCP サーバーを起動します（stdio）
```

`<t>` = 秒（`90`）またはシートに記載されたタイムコード（`1:30`, `1:07.3`）。参照 [時刻値](#time-values) 完全な文法および [MCP サーバー](/squish/ja/rifarensu/mcp.md) について `squish mcp`.

要件: Node ≥ 20, `ffmpeg` + `ffprobe` PATH にあること。すべてはお使いのマシン上で実行されます — 詳細は [プライバシーとデータフロー](/squish/ja/purimitibu/privacy-and-data-flow.md).

## フラグ

| フラグ         | 値                                | 必須  | デフォルト        | 制約                                              | 意味                                                                                       |
| ----------- | -------------------------------- | --- | ------------ | ----------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `--density` | `3x3` \| `4x4` \| `5x5` \| `6x6` | いいえ | `3x3`        | 次の4つの値のいずれかである必要があります                           | 1シートあたりのフレーム数: 9 / 16 / 25 / 36。 `3x3` 復元します *何が* 起きたか; `4x4`–`6x6` 把握する *どのように* 実行されたか。 |
| `--start`   | 時刻（`<t>`)                        | いいえ | `0`          | 0以上で、かつクリップの終了前であること                            | ズームウィンドウの開始時刻、 **ソース動画のクロック** （絶対値です。直前のウィンドウからの相対値にはなりません）。                             |
| `--end`     | 時刻（`<t>`)                        | いいえ | クリップの終了      | 以降である必要があります `start`；クリップの終了を超える値はその終了位置に丸められます | ズームウィンドウの終了時刻。絶対値です。                                                                     |
| `--out`     | ディレクトリ                           | いいえ | 入力ファイルと同じ場所に | 存在しない場合は（再帰的に）作成されます                            | 出力シートの書き込み先です。                                                                           |
| `--json`    | —                                | いいえ | オフ           | —                                               | 機械可読レポート（[以下](#--json-output)）を、人間向けサマリーの代わりに stdout に出力します。                             |

## 位置引数

位置引数は1つだけです。ローカルの動画ファイルへのパス（ffmpeg がデコードできるものなら何でも可）を指定します。絶対パスに解決され、相対パスは現在の作業ディレクトリを基準に解決されます。

## 使用方法エラー

入力に問題がある場合は、エラーメッセージ **と使用方法テキストを** stderr に出力して終了します `1`。具体的な条件とメッセージは次のとおりです:

| 条件                                  | メッセージ                                                      |
| ----------------------------------- | ---------------------------------------------------------- |
| 位置引数がありません                          | `<video> 入力がありません`                                         |
| 2つ目の位置引数                            | `1回の実行につき動画は1つだけです — 2つ目の入力がありました: <arg>`                  |
| 認識されないフラグ                           | `不明なフラグ: <arg>`                                            |
| `--density` 欠落しているか、列挙型に含まれていません    | `--density は 3x3\|4x4\|5x5\|6x6 のいずれかでなければなりません`           |
| `--start` / `--end` 欠落しているか、解析できません | `--start には時刻が必要です — 秒（90）またはタイムコード（1:30）` （同じ形式で `--end`) |
| `--out` ディレクトリが指定されていません            | `--out にはディレクトリが必要です`                                      |
| `squish mcp` 余分な引数が付いている場合          | `squish mcp は引数を取りません`                                     |

実行すると `squish` 引数なしで使用方法テキストを表示して終了します `1`; `--help` / `-h` 使用方法テキストを表示して終了します `0`.

## 時刻値

`--start` と `--end` 受け付ける形式:

* 単純な秒数: `90`, `67.4`
* シートに記載されたそのままのタイムコード: `1:30`, `120:30` （分は上限なし）、 `1:07.3` （小数秒）、または `01:02:03` (`h:mm:ss`)

シートに表示されるものはすべて有効な入力です — 参照 [双方向変換特性](/squish/ja/rifarensu/sheet-format.md#round-trip-property) シート形式仕様の正確な文法を参照してください。

### ウィンドウの意味論

両方の境界は **ソース動画上の絶対値です** すべてのズーム深度で同様です — ウィンドウ付きの実行ではタイムコードを再基準化しません。解決ルール（クリップを調べた後、次の順序で確認します）:

* 省略した場合 `--start` → `0`。省略した場合 `--end` → クリップの終了。
* ある `--end` がクリップの終了を超える場合は **丸められます** クリップの再生時間に（「5:00 から終わりまで」のように、再生時間を知らなくても動作します）。
* 負の `--start` 場合は失敗します: `start は 0以上の時刻でなければなりません`.
* ある `--start` がクリップの終了時刻以降である場合は失敗します: `start (<t>) がクリップの終了時刻 (<duration>) 以降です`.
* 空のウィンドウ（end ≤ start。end の丸め後も含む）は失敗します: `ウィンドウが空です — end (<t>) は start (<t>) より後でなければなりません`.
* 次より小さいウィンドウは **1 セルあたり 2 ms** 選択した密度では学習用エラーで失敗します: `ウィンドウが小さすぎて個別に扱えません: <N> セルを <X> ms に収めています（エンジンはミリ秒精度でシークします — この密度での最小値は約 <2N> ms です）。ズームアウトするか、密度を下げてください`。ちょうど下限値のウィンドウは受け入れられます。参照 [適応的精度](/squish/ja/rifarensu/sheet-format.md#adaptive-precision) この下限が存在する理由について

## 出力ファイル

シートは次の形式で書き出されます `<basename>.sheet-N.jpg` (`N` （1から始まり、時刻順です）。ここで `<basename>` は拡張子を除いた入力ファイル名です — 参照 [ファイル名契約](/squish/ja/rifarensu/sheet-format.md#filename-contract)。既定の出力先は入力ファイルのディレクトリです; `--out <dir>` がそれを上書きします。

## --json 出力

と組み合わせると、 `--json`、stdout にはちょうど1つの JSON オブジェクトが出力されます — 固定された `squish-cli-v0` 契約（参照 [安定性とバージョニング](/squish/ja/rifarensu/stability.md)）。キー順は固定です:

```json
{
  "input": "/abs/path/clip.mov",
  "duration": 20.275,
  "frames": 9,
  "sheets": 1,
  "files": ["/abs/path/clip.sheet-1.jpg"],
  "warnings": [],
  "contract": "squish-cli-v0"
}
```

| キー         | 型         | 存在                                        | 意味                                                                                                                                       |
| ---------- | --------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `input`    | string    | 常に                                        | 入力動画の解決済み絶対パスです。                                                                                                                         |
| `duration` | number    | 常に                                        | 再生時間 **クリップ全体** 秒単位です — ウィンドウ付きの実行でも、ウィンドウの長さではありません。                                                                                    |
| `window`   | object    | 次の場合のみ `--start` および/または `--end` が指定された場合 | `{ "start": <s>, "end": <s> }` — その **解決済みの** 境界を秒単位で表したものです（既定値の適用と終了側の丸め後、ミリ秒精度）。ウィンドウが要求されていない場合は存在しません。次の間に現れます `duration` と `フレーム`. |
| `フレーム`     | number    | 常に                                        | サンプリングした総フレーム数（`シート数 × セル数`）。読み取れないフレームもカウントされます — それらは `warnings`.                                                                      |
| `sheets`   | number    | 常に                                        | 生成されたシートファイル数です。                                                                                                                         |
| `files`    | string\[] | 常に                                        | シート順の絶対出力パスです。                                                                                                                           |
| `warnings` | string\[] | 常に                                        | 致命的ではない問題。たとえば `シート1 フレーム3: 読み取り不能 — セルは黒のまま`.                                                                                           |
| `契約`       | string    | 常に                                        | `"squish-cli-v0"` — これを解析して、破壊的変更を検出してください。                                                                                              |

ウィンドウ付き実行の例:

```json
{
  "input": "/abs/path/clip.mov",
  "duration": 200.5,
  "window": { "start": 60, "end": 90 },
  "frames": 25,
  "sheets": 1,
  "files": ["/abs/path/clip.sheet-1.jpg"],
  "warnings": [],
  "contract": "squish-cli-v0"
}
```

（--json なしでは `--json`、stdout は人間向けサマリーになります（出力パス、 `警告:` 行、および `サマリー: duration=…s sheets=… frames=…` 行）。契約として安定性が保証されるのは `--json` object のみです。人間向け出力を解析しないでください。

## 終了コード

| コード | 意味                                                                                                                                                                                |
| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `0` | 成功。さらに: `--help` / `-h`.                                                                                                                                                          |
| `1` | 失敗全般。使用方法エラーではメッセージと使用方法テキストを stderr に出力し、実行時エラー（たとえば `入力が見つかりません: <path>`、ウィンドウエラー、ffmpeg の失敗）はメッセージを stderr に出力します。実行すると `squish` 完全に引数なしだと使用方法テキストを **stdout** に出力して終了します `1`. |

stdout に書き込まれるのはレポートだけです。例外は使用方法テキストです。 `--help` / `-h` 使用方法を stdout に出力して終了します `0`；実行すると `squish` で **完全に引数なしの場合** も使用方法を stdout に出力しますが、終了します `1`。stdout を機械可読出力専用にするラッパーは、解析前に終了コードを確認してください。それ以外の失敗はすべて stderr のみに書き込まれます。

## 一時フレームのクリーンアップ

抽出されたフレームは、OS の一時ディレクトリ配下の実行ごとの一時ディレクトリに保存されます。実行終了時には常に削除されます — **成功時でもエラー時でも**。残るのは `.sheet-N.jpg` ファイルだけです。

## 例

```bash
# 概要: クリップ約90秒ごとに1枚の 3×3 シートを生成し、入力の隣に書き出します
squish clip.mov

# より高密度なグリッド + 機械可読出力
squish clip.mov --density 5x5 --json

# ズーム: 1:00–1:30 をより高密度で再度 squish します — タイムコードは絶対値のままです
squish clip.mov --start 1:00 --end 1:30 --density 5x5

# 前のシートで見つけた1秒未満の範囲を、指定したディレクトリへ掘り下げます
squish clip.mov --start 1:07.3 --end 1:09 --density 4x4 --out ./sheets --json
```

ズームのパターン（概要 → 範囲を見つける → 再実行して `--start`/`--end` → より細かいタイムコード）という流れは [ナビゲーションループ](/squish/ja/purimitibu/the-navigation-loop.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://getsquish.gitbook.io/squish/ja/rifarensu/cli.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.