コマンド一つで画像を圧縮。
ウェブ版と同じエンジンを、ターミナル・ビルド・エージェントの中へ。Node 20 以降が必要で、テレメトリはなく、画像は圧縮が終わった瞬間に削除されます。
+70エージェントに入れてもらう
この一文を Claude Code・Codex などお使いのコーディングエージェントに送るだけ —— このドキュメントを読んで自分でセットアップします。
このドキュメントを見て pipic CLI をインストールして、終わったらサインインの方法を教えて：https://pipic.cc/cliなぜ CLI か
エージェント向けの出力
NDJSON と安定した終了コード。エージェントがそのまま分岐できます —— 推測が必要な自然文ではありません。
フォルダ丸ごと、コマンド一つ
その場で置き換えるか、新しいディレクトリへ —— ローカルのバッチもビルド成果物も同じです。
サインインは一度だけ
以降はスクリプトも CI（PIPIC_TOKEN 経由）もエージェントも無人で動き、再承認は不要です。
既定で安全
--replace か -o を明示しない限り何も触りません。書き込みはアトミックで、小さくならないファイルはそのまま残します。
クイックスタート
エージェント · まず skill を入れるskill を一度入れれば、エージェントが自分で pipic を見つけます —— ツール名を挙げる必要も、オプションを繰り返す必要もありません。
CLI をインストール
Node 20 以降skill をインストール
Claude Code・Codex・Cursor ほか 70 種類以上サインインを承認
1台につき1回あとは頼むだけ
ツール名もオプションも不要- pipic login は自分で実行しない —— 承認はユーザーに任せる。
- skipped は失敗ではない —— 「すでに十分小さい」などの理由が付いている。
- 一部失敗したら、失敗したファイルだけ再実行する —— 全部やり直すと枠を二重に消費する。
一度きりの作業や、skill に対応していないエージェント向け —— コマンドをそのまま渡してください。契約の全文は次のセクションにあります：
Use the pipic CLI to compress the images in ./assets, replacing them in place: pipic ./assets --replace --json Run `pipic -h` for more.
エージェントが ~/.config を参照できないコンテナやサンドボックスで動いていますか？アカウントページでトークンを作成し、その環境で PIPIC_TOKEN を設定してください。
自分で実行する
人 · スクリプト · CIインストール
Node 20 以降何もインストールしない
npxブラウザなし —— SSH・コンテナ
device codeCI とサンドボックス
PIPIC_TOKENコマンド
pipic <パス…>ファイルまたはディレクトリを圧縮します。これがデフォルトのコマンドです。pipic login [--no-browser]ブラウザまたはデバイスコードでこのマシンを認証します。pipic logoutサインアウトし、このマシンのトークンを失効させます。pipic whoamiサインイン中のアカウントとプランを表示します。pipic quota今月の残り利用枠を表示します。pipic token listトークンをプレフィックスと最終利用日時つきで一覧表示します。pipic token createウェブサイトで作成するためのリンクを表示します —— セキュリティ上、トークンの作成は必ずウェブ上で行い、CLI 自体では作成しません。pipic token revoke <id>自分のトークンを失効させます。通常 1 分程度で反映されます。login・logout・whoami・quota・token は、パスとして扱われる前にサブコマンドとして優先的にマッチします。同じ名前のフォルダを圧縮したい場合は ./login や login/ のように書いてください —— パス区切りを含む形であれば圧縮コマンドとして扱われます。
圧縮オプション
--replace元の画像をその場で上書きします —— アトミックな置き換え、権限を維持、シンボリックリンクを解決。
-o, --out <dir>結果をこのディレクトリに書き出します。
--jsonファイルごとに 1 行の NDJSON を出力します —— スクリプトやエージェント向け。
--concurrency <n>並列アップロード数。デフォルトは 4。
--replace か -o のどちらか一方を必ず指定してください —— 両者は排他的で、どちらもデフォルトではありません。どちらも指定しない場合、pipic は用法エラー（終了コード 2）で終了します。
知っておきたいこと
- 結果が実際に小さくなった場合のみ書き戻します —— すでに最適化済みの画像はスキップされ、理由が表示されます。-o の場合は元の画像がそのままコピーされるため、出力ディレクトリは常に完全な一式になります。
- --replace は一時ファイルに書き込んでからリネームするため、Ctrl-C で中断しても中途半端なファイルが残りません。
- 8 MB を超えるファイルは明確な理由つきでスキップされ、黙って捨てられることはありません。
- JPG・PNG・WebP・AVIF に対応。テレメトリは一切送信されません。
- -o では、別々のサブフォルダにある同名ファイル同士が衝突します。pipic はどちらを残すか推測せず、両方をエラーとして報告します。
JSON 出力コントラクト
--json はファイルごとに 1 行、固定 6 フィールドの JSON オブジェクトを出力します：
file渡したパスがそのまま入ります。status"ok"・"skipped"・"error" のいずれか —— それ以外の値は取りません。before元のサイズ（バイト）。after圧縮後のサイズ（バイト）—— skipped/error 行では 0。saved節約したバイト数（before から after を引いた値）—— 割合ではありません。errorskipped と error の行にのみ存在 —— コードではなく、人が読める理由です。終了コード
これは安定した契約です：スクリプトやエージェントは status と終了コードで分岐してください —— error の文字列内容で判定してはいけません。
HTTP API
Node が使えない環境でも、同じ圧縮エンジンを HTTP で直接呼び出せます —— 1 リクエストにつき画像 1 枚、SDK も multipart フォームも不要です。
AuthorizationBearer <token> —— すべてのリクエストで必須。Content-Typeimage/png、image/jpeg、image/webp、image/avif のいずれか —— 必須。実際に送るバイト列と一致させてください。X-Original-Name任意。先に URL エンコードしてください —— レスポンスには encodeURIComponent で使える文字だけがそのまま返ります。Body画像の生バイナリ。multipart/form-data ではありません。1 リクエストにつき画像 1 枚、最大 8MB。レスポンス
200 OK のレスポンスボディは圧縮済み画像そのもの —— 入力と同じ形式で返ります。Content-Type は圧縮後の形式を示し、取得できれば Content-Length と X-Original-Name も付きます。
トークンを取得
API は CLI と同じ Personal Access Token を使います。GitHub または Google でサインインし、アカウントページで発行してください —— 平文のトークンはその場限りしか表示されないので、安全な場所に保存してください。
エラー
200 以外のレスポンスはすべてこの形の JSON エラーを返します。判定は message の文字列ではなく code フィールドで行ってください —— 実例はこちら：
400INVALID_TYPE —— Content-Type が未指定、または画像タイプでない／NO_FILE —— リクエストボディが空401UNAUTHORIZED、TOKEN_EXPIRED、TOKEN_REVOKED —— 再サインイン、または新しいトークンを作成413FILE_TOO_LARGE —— 8MB 超過415UNSUPPORTED_TYPE —— 圧縮対象外の image/* タイプ（対応は PNG・JPEG・WebP・AVIF のみ）429RATE_LIMITED（Retry-After ヘッダーを参照）または MONTHLY_QUOTA_EXCEEDED —— 今月の利用枠を使い切った502UPSTREAM_ERROR —— 圧縮バックエンドがこの画像を拒否しました。同じバイト列を再送しても結果は変わりません。この試行は割り当てに払い戻されます503UPSTREAM_ERROR または ALL_KEYS_EXHAUSTED —— 一時的に容量が不足しています。バックオフして再試行できます。この試行は割り当てに払い戻されます知っておきたいこと
- リクエストは圧縮処理に受け付けられた時点で利用枠を 1 消費します —— そのあと 400・413・415 で失敗した場合も同様です。その前に拒否されたリクエストは消費しません：あらゆる 401、429 RATE_LIMITED、および宣言された Content-Length ヘッダーだけを理由に拒否されたファイルです。こちら側の問題（502/503）で失敗した場合は、その分は自動的に返却されます。
すべてのヘッダーとエラーコードを機械可読な 1 ファイルで確認するには： /openapi.json
よくある質問
エージェントが指示していないファイルを触ることはありますか？
ありません —— pipic は --replace か -o <dir> の明示指定を必須とし、どちらもなければ実行を拒否します。そのエラーを報告する前に、リクエストが送信されることも一切ありません。
一度サインインすれば、エージェントはずっと使い続けられますか？
はい。認証情報はこのマシンの ~/.config/pipic/config.json に保存されており、あなたとして動くどのツールも読み取れます —— エージェントごとに追加の承認は不要です。
エージェントが「サインインしていません」と言ってきたら？
多くの場合、~/.config が見えないコンテナやサンドボックスで動いています。アカウントページでトークンを作成し、その環境の PIPIC_TOKEN として設定してください。
無料の利用枠を使い切るとどうなりますか？
pipic は終了コード 4 で終了し、自動的に課金されることはありません。Free は月 100 枚、Pro なら月 5,000 枚まで増えます。
画像はどこかに保存されますか？
いいえ —— 圧縮が完了した瞬間にサーバーから削除され、長期的に保存されることはありません。