CLI 指令

Bannerify CLI 有三個指令：config、create 和 whoami。

bannerify <command> [options]

執行 bannerify --help 或 bannerify <command> --help，就能印出指令的選項。如果尚未儲存金鑰，且終端機是互動式的，不帶任何引數執行 bannerify 會啟動引導式設定；其他情況則會印出說明。

全域旗標

旗標	說明
-v, --version	印出 CLI 版本
-h, --help	印出說明。每個子指令都適用

config

管理 CLI 在多次執行之間保留的設定。這些指令的運作方式就像 git config。

指令	說明
bannerify config set <key> [value]	儲存一個值。省略 value 時，CLI 在互動式終端機中會要求你輸入，在腳本中則會失敗
bannerify config get <key>	印出一個值
bannerify config list	印出所有已儲存的值
bannerify config delete <key>	移除一個值。如果該值未設定，會以 1 結束

設定項目

設定項目	說明
apiKey	CLI 傳送的 API 金鑰
baseUrl	API 的基底網址。預設為 https://api.bannerify.co/v1
defaultFormat	沒有 --format 時使用的圖片格式。預設為 png
outputDir	沒有 --out 時，輸出檔案所在的資料夾

CLI 在儲存值時不會檢查它。若 defaultFormat 不是 png、jpeg 或 webp，會在你稍後執行 create image 時失敗。

get 和 list 會隱藏 apiKey 的中間部分，例如 abcd****mnop。加上 --show 就能完整印出：

bannerify config get apiKey --show

沒有指定值的 config set apiKey 會要求你輸入金鑰，並隱藏你輸入的內容。若想在貼上很長的金鑰時看見內容，請加上 --show：

bannerify config set apiKey
bannerify config set baseUrl https://api.bannerify.co/v1
bannerify config set defaultFormat webp
bannerify config set outputDir ./renders
bannerify config delete defaultFormat

get 和 list 會把值印到標準輸出，list 還會把設定檔的路徑印到標準錯誤輸出。設定檔是 $XDG_CONFIG_HOME/bannerify/config.json 或 ~/.config/bannerify/config.json，權限為 0600。

create

從範本生成圖片或 PDF。

bannerify create image <templateId> [options]
bannerify create pdf <templateId> [options]

選項

選項	說明
-o, --out <path>	輸出檔案。使用 --out=- 可把檔案寫到標準輸出。路徑中缺少的資料夾，CLI 會自動建立
--format <format>	圖片格式：png、jpeg 或 webp。僅適用於圖片。預設為 png，或設定中的 defaultFormat
--modifications '<json>'	modification 的 JSON 陣列。使用 - 可從標準輸入讀取
--modifications-file <path>	從 JSON 檔案讀取陣列。使用 - 表示標準輸入
--api-key <key>	這個指令使用此 API 金鑰
--base-url <url>	這個指令使用此 API 基底網址
--json	把結果以 JSON 印到標準輸出
-q, --quiet	隱藏錯誤以外的所有訊息

沒有 --out 時，CLI 會把 <templateId>.<format> 寫到目前的資料夾；如果你設定了 outputDir，則寫到該資料夾。PDF 的副檔名是 pdf。

Modifications

--modifications 接受物件陣列。每個物件用 name 指定一個圖層，並設定它的欄位。MCP 工具接受的物件格式在這裡無法使用。

bannerify create image tpl_xxx -o out.png \
  --modifications '[{"name":"title","text":"Hello world"}]'

如果你同時傳入 --modifications 和 --modifications-file，CLI 會把兩個陣列接在一起，檔案的內容排在前面。

不存在的圖層名稱會被忽略，也不會出現錯誤，所以當某個值沒有變更時，請檢查拼字。每種圖層類型的欄位，請見 Modifications。

範例

# 以 WebP 輸出，並覆寫一段文字
bannerify create image tpl_xxx --format webp -o out.webp \
  --modifications '[{"name":"title","text":"Summer sale"}]'

# 用相同的圖層生成 PDF
bannerify create pdf tpl_invoice -o invoice.pdf \
  --modifications '[{"name":"total","text":"$29.00"}]'

# 把圖片位元組輸出到標準輸出，交給管線中的下一個指令
bannerify create image tpl_xxx --out=- --quiet > out.png

# 從檔案讀取 modification
bannerify create image tpl_xxx -o out.png --modifications-file ./data.json

whoami

檢查 API 金鑰，並印出它所屬的工作區。

bannerify whoami

選項	說明
--api-key <key>	檢查這個金鑰，而不是已儲存的金鑰
--base-url <url>	使用這個 API 基底網址
--json	把結果以 JSON 印到標準輸出

+ Authenticated as Acme
  project id: proj:xxxxxxxxxx
  created:    2026-01-14T09:12:31.000Z
  key source: config

key source 是 flag、env 或 config，可以告訴你腳本使用的是哪一個金鑰。沒有 --json 時，whoami 會把這段文字印到標準錯誤輸出，因此在腳本中請用 --json 讀取結果。

在新環境中請先執行 whoami。它會在一個很長的批次失敗之前，先回報金鑰的問題。

從腳本或代理程式使用

當標準輸入或標準輸出不是終端機，或是設定了 CI 時，CLI 絕不會要求輸入。缺少金鑰時會立即失敗，並印出可以修正問題的指令。

行為	細節
要求輸入	僅限互動式終端機
標準輸出	只有資料：使用 --out=- 時是檔案位元組，使用 --json 時是 JSON 結果，以及 config get 和 config list 的輸出
標準錯誤輸出	訊息、進度和錯誤
金鑰來源	--api-key 旗標，接著是 BANNERIFY_API_KEY，再來是設定檔

JSON 輸出

加上 --json，就能從腳本讀取結果。成功時，create image 會印出一個物件：

{
  "ok": true,
  "command": "create image",
  "templateId": "tpl_xxx",
  "format": "png",
  "path": "/home/dev/out.png",
  "bytes": 80734
}

create pdf 不含 format。當你把檔案寫到標準輸出時，path 為 stdout。whoami 會印出工作區和金鑰來源：

{
  "ok": true,
  "project": {
    "id": "proj:xxxxxxxxxx",
    "name": "Acme",
    "createdAt": "2026-01-14T09:12:31.000Z"
  },
  "keySource": "config"
}

create 失敗時，會印出 API 回傳的錯誤物件，並以非零的代碼結束：

{
  "ok": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "template tpl_xxx not found",
    "docs": "https://bannerify.co/docs/api-reference/errors/code/NOT_FOUND",
    "requestId": "req:1a2b3c4d5e6f7a8b"
  }
}

whoami --json 失敗時，error 只含有 message。

請不要同時使用 --out=- 和 --json。兩者都會寫到標準輸出，JSON 那一行會接在檔案位元組後面。請改為把檔案寫到某個路徑。

結束碼

代碼	意義
0	指令成功
1	其他任何錯誤：缺少金鑰、不支援的格式、無效的 modification、未知的設定項目，或來自 API 的錯誤
2	驗證錯誤。當錯誤碼是 401、403、UNAUTHORIZED 或 FORBIDDEN 時，create 會以 2 結束。whoami 的金鑰檢查失敗時會以 2 結束

API 會把未知的金鑰回報為 BAD_REQUEST，所以金鑰錯誤時，create 會以 1 結束。要檢查金鑰，請執行 whoami：它會以 2 結束；加上 --json 時則以 1 結束。

bannerify create image tpl_xxx -o out.png --quiet || echo "generation failed with code $?"

疑難排解

症狀	原因	解決方式
No API key found	工作階段不是互動式的，且沒有設定金鑰	設定 BANNERIFY_API_KEY、傳入 --api-key，或執行一次 bannerify config set apiKey
whoami 印出 Project not found 並以 2 結束	金鑰不存在，或已被刪除	在 API Keys 頁面建立金鑰，並用 bannerify config set apiKey 儲存
Unsupported format	--format 或 defaultFormat 不是 png、jpeg 或 webp。不提供 SVG 輸出	使用這三種格式之一
Invalid modifications	這個值不是有效的 JSON、不是陣列，或是檔案路徑錯誤	傳入物件陣列，例如 [{"name":"title","text":"Hi"}]
結束碼 1 和 NOT_FOUND	範本 ID 不存在	用範本卡片選單中的 Copy Template ID 複製 ID
結束碼 1 和 BAD_REQUEST	API 金鑰錯誤，或某個 modification 的值型別不對	訊息會指出原因。要測試金鑰，請執行 bannerify whoami
結束碼 1 和 USAGE_EXCEEDED	工作區已達到生成次數上限	請見用量額度與限制
以 TypeError: fetch failed 開頭的堆疊追蹤	create 無法連線到 API，例如網路中斷或 baseUrl 錯誤。指令會以 1 結束	檢查你的網路連線，並執行 bannerify config get baseUrl
某個值沒有變更	圖層名稱不符合任何圖層，Bannerify 會忽略它	對照 Modifications 檢查名稱
二進位資料佔滿終端機	--out=- 會把檔案寫到標準輸出	重新導向，例如 --out=- > out.png

瞭解更多

• 從終端機生成
• 處理錯誤
• 用量額度與限制