命令列（jpgboost-cli）

jpgboost-cli 無需開啟圖形介面即可壓縮您的圖片。它是指令碼、排程工作與持續整合場景的理想工具。

Pro 功能

您的授權最多可涵蓋 2 次供個人使用的安裝。應用程式與 CLI 即使安裝在同一部 Mac 上，也各自計為一次獨立安裝。它們會以裝置形式顯示在「偏好設定 > 授權」中。

一部僅執行 CLI、用於持續整合或排程工作等自身自動化用途的伺服器，可以佔用這兩個名額中的一個，而無需額外購買授權。更多資訊請參閱在伺服器上使用授權與每位使用者一份授權部分。

命令列的用途

jpgboost-cli 是內建於 JPGBoost.app 中的獨立可執行檔，既不依賴本機 API，也不依賴正在執行的應用程式執行個體：它直接使用相同的解碼與編碼引擎，因此產生的檔案與圖形介面完全一致。

在無需開啟任何介面的場景中，它是理想的進入方式：Shell 指令碼、排程工作、持續整合，或處理大量檔案時均可使用。

無需另行安裝

jpgboost-cli 已包含在 JPGBoost.app 中。由於使用的是應用程式中已整合的元件，因此既不需要編譯，也不需要安裝任何程式庫。

讓指令可被隨處呼叫

該二進位檔位於應用程式包內。您可以透過其完整路徑直接呼叫：

/Applications/JPGBoost.app/Contents/MacOS/jpgboost-cli --help

為了能在任何資料夾中執行 jpgboost-cli，請建立一次符號連結：

sudo ln -s /Applications/JPGBoost.app/Contents/MacOS/jpgboost-cli \
  /usr/local/bin/jpgboost-cli

jpgboost-cli --help

由於該連結指向應用程式包，因此在應用程式更新後依然有效。本頁中的範例均假設已完成此項設定；若未設定，請將 jpgboost-cli 取代為上述完整路徑。

如果您不使用 sudo

只要該目錄包含在您的 PATH 中，您也可以使用個人資料夾取代 /usr/local/bin，例如 ~/bin。另一個簡單的替代方案是在 ~/.zshrc 中新增一個別名。

在伺服器上使用授權

僅執行 CLI 的機器（例如沒有圖形介面的伺服器），可以無需使用 JPGBoost.app 完成啟用與管理。

# 透過 CLI 取得此機器的識別碼
jpgboost-cli --machine-id

# 使用購買後透過電子郵件收到的權杖進行首次啟用
jpgboost-cli --activate ACT-XXXX-XXXX-XXXX-XXXX-XXXX

# 從這部已啟用的伺服器產生用於新增另一部裝置的配對碼
jpgboost-cli --add-device

# 使用在其他位置（應用程式或另一個 CLI）產生的配對碼加入授權
jpgboost-cli --pair XXXX-XXXX

# 如果伺服器上有更新版本的授權，則取得該版本
jpgboost-cli --sync

# 已使用的安裝數量 / 上限，及其清單 — 本機讀取，無需網路呼叫
jpgboost-cli --devices

應用程式與 CLI 計為兩次獨立安裝

應用程式與 CLI 即使在同一部 Mac 上使用，也會被視為兩次獨立安裝。它們各自擁有獨立的安裝識別碼，因此會佔用 Pro 授權所允許的兩個名額中的一個。

因此，您可以以多種方式使用授權，例如：您 Mac 上的應用程式配合伺服器上的 CLI；同一部 Mac 上同時使用應用程式與 CLI；兩部不同 Mac 上均使用應用程式；或者僅在從不開啟應用程式的伺服器上使用 CLI。

語法與選項

jpgboost-cli <檔案...> --output <資料夾> [選項]

選項	功能	預設值
`--output <資料夾>`	目標資料夾，若不存在則自動建立	必填
`--quality <1-100>`	壓縮畫質	75
`--format <格式>`	`png`、`jpeg`、`heic`、`avif`、`webp` 或 `jxl` 之一	`jpeg`
`--profile <名稱>`	套用具名的匯出設定檔	無
`--jobs <N>`	平行處理的檔案數量	核心數量
`--json`	輸出結構化 JSON，而非可讀文字	關閉
`--help`	顯示說明資訊	—

基礎範例

# 將兩個檔案轉換為 WebP，畫質設為 60
jpgboost-cli foto1.jpg foto2.png --quality 60 --format webp --output ./compressed
# foto1.jpg: 4.2 MB -> 890 KB (-79%) -> ./compressed/foto1.webp
# foto2.png: 1.8 MB -> 620 KB (-66%) -> ./compressed/foto2.webp
#
# 已處理 2 個檔案，0 個失敗。

# 將整個資料夾轉換為 AVIF
jpgboost-cli ~/Pictures/export/*.png --format avif --quality 65 --output ~/Pictures/web

批次處理與平行化

對於數百甚至數千個檔案，--jobs 選項可同時處理多張圖片。每個檔案都會被獨立解碼、編碼，隨後釋放：記憶體用量不會隨等待處理的檔案數量增長，而只與 --jobs 的數值相關。

# 同時處理 8 個檔案
jpgboost-cli ~/Photos/batch/*.jpg --jobs 8 --format webp --output ~/Photos/web

# 逐一處理，以降低共用裝置上的負載
jpgboost-cli ~/Photos/batch/*.jpg --jobs 1 --format webp --output ~/Photos/web

實測效能提升

在一批 12 個檔案的測試中，--jobs 8 比 --jobs 1 快約 4 倍。實際提升幅度取決於您 Mac 的核心數量以及目標格式：AVIF 與 JPEG XL 的編碼速度明顯慢於 JPEG 或 HEIC。

使用匯出設定檔

--profile 選項可重複使用在應用程式或透過 API 建立的設定檔，僅會補充您未明確指定的部分。

# 格式、畫質與資料夾均來自設定檔
jpgboost-cli --profile "Web JPEG" *.png

# 此處明確指定的資料夾優先，其餘部分來自設定檔
jpgboost-cli --profile "Web JPEG" --output ./de/livery *.png

CLI 還可以直接建立或更新設定檔，無需經過偏好設定或本機 API：

jpgboost-cli --create-profile "Web JPEG" --format jpeg --quality 70 --output ./compressed

--format 與 --quality 為必填項，--output 為可選項（指定的資料夾必須已經存在）。若名稱已被使用，則會取代現有的設定檔，而非建立重複項——這與應用程式的「設定檔」分頁及本機 API 的行為一致。與 CLI 的其他功能一樣，此功能同樣需要 JPGBoost Pro。

JSON 輸出

使用 --json 時，輸出結果為一個 JSON 陣列，其中每個已處理的檔案對應一個 JSON 物件，其結構與本機 API 的回應相同，便於與 jq 或其他工具進行串接。

jpgboost-cli *.png --format webp --output ./output --json

# 與 jq 串接：僅保留出現錯誤的檔案
jpgboost-cli *.png --format webp --output ./output --json \
  | jq '.[] | select(.error != null)'

可用欄位：path、originalSizeBytes、compressedSizeBytes、ratio、destination 與 error。

結束代碼

代碼	意義
`0`	所有檔案均處理成功
`77`	此裝置上沒有有效的 Pro 授權
非零值	至少有一個檔案處理失敗；可直接用於指令碼或持續整合流程

同名檔案

兩個基礎名稱相同的輸入檔案，自然會指向同一個輸出結果。例如，將 a/foto.jpg 與 b/foto.png 轉換為 WebP 時，二者都會產生 foto.webp。

JPGBoost 不會覆寫它們：第二個檔案會取得一個獨立的名稱。

a/foto.jpg  ->  foto.webp
b/foto.png  ->  foto-2.webp

命名按參數的順序分配，與使用 --jobs 時的執行順序無關，因此結果具有可重現性。應用程式、捷徑、AppleScript 與監控資料夾均遵循相同的規則。

重複執行同一次匯出

此規則僅適用於不同檔案之間發生的命名衝突。將同一個檔案再次匯出至同一資料夾，會直接取代其先前的輸出結果，而不會累積產生 foto-2、foto-3 等檔案。

驗證安裝

您可以隨時驗證該指令是否回應正常：

jpgboost-cli --help