從終端機生成

Bannerify CLI 可以從終端機生成圖片和 PDF。它使用與 REST API 相同的範本和 API 金鑰，因此你只要一個指令就能繪製檔案，並把結果交給另一個工具。本頁適合在 shell 中工作的開發者，以及會呼叫 shell 的腳本和代理程式。

在以下情況可以使用 CLI：

在建置、部署或排程工作中繪製檔案。
從 shell 腳本執行大量繪製。
讓代理程式或腳本不用寫程式碼就能建立檔案。

開始之前

一個至少有一個範本的 Bannerify 帳號。請用範本卡片選單中的 Copy Template ID 複製它的 ID。
一組 API 金鑰。請在 API Keys 頁面用 New API key 建立。步驟請見驗證請求。
Node.js 18 或更新版本。

安裝

npm install -g bannerify-cli

若要不安裝套件就執行指令：

npx bannerify-cli <command>

儲存 API 金鑰

只要儲存一次金鑰，做法就像使用 git config：

bannerify config set apiKey YOUR_API_KEY

在互動式終端機中，如果還沒有儲存金鑰，你也可以不帶任何引數直接執行 bannerify。CLI 會要求你輸入金鑰、隱藏你輸入的內容、驗證金鑰，然後儲存。在互動式終端機中，任何需要金鑰的指令找不到金鑰時，也會啟動相同的設定流程。在腳本中，指令會直接失敗。

CLI 會把金鑰寫入 $XDG_CONFIG_HOME/bannerify/config.json；如果沒有設定 XDG_CONFIG_HOME，則寫入 ~/.config/bannerify/config.json。檔案的權限會設為 0600。

檢查金鑰

bannerify whoami

這個指令會印出工作區的名稱和 ID、建立日期，以及 CLI 在哪裡找到金鑰：

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

生成圖片

bannerify create image tpl_xxx -o out.png

CLI 會把圖片儲存為 out.png，並印出它的路徑和大小：

+ Created image /home/dev/out.png (80734 bytes, png)

沒有加上 -o 時，檔案會命名為 <templateId>.<format>，例如 tpl_xxx.png，並儲存在目前的資料夾。

若要變更範本的圖層，請傳入 --modifications：

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

這個值是 JSON 陣列。每個項目用 name 指定一個圖層，並設定它的欄位，例如 text 或 src。每種圖層類型的欄位，請見 Modifications。

用 --format 選擇格式：png（預設）、jpeg 或 webp。

生成 PDF

bannerify create pdf tpl_xxx -o out.pdf

PDF 可以使用相同的 --modifications 值：

bannerify create pdf tpl_invoice -o invoice.pdf \
  --modifications '[{"name":"total","text":"$29.00"}]'

在管線中使用

CLI 把標準輸出留給資料，把標準錯誤輸出留給訊息，因此檔案的位元組可以乾淨地傳給下一個指令。用 --out=- 就能把檔案寫到標準輸出：

bannerify create image tpl_xxx --out=- --quiet > out.png

處理批次時，每個結果一完成就送到它的目的地：

for id in tpl_a tpl_b tpl_c; do
  bannerify create image "$id" --out=- --quiet | rclone rcat "remote:$id.png"
done

若要傳入很長的 modification 陣列，請把它存成檔案，或用管線傳入：

bannerify create image tpl_xxx -o out.png --modifications-file ./data.json
echo '[{"name":"title","text":"From stdin"}]' | \
  bannerify create image tpl_xxx -o out.png --modifications-file -

CLI 指令說明了適合腳本使用的 JSON 輸出和結束碼。

金鑰的取得順序

CLI 會依照以下順序尋找 API 金鑰：

--api-key 旗標。
BANNERIFY_API_KEY 環境變數。
已儲存的設定。

你可以在設定中保留一個金鑰，並在單一指令或容器中改用其他金鑰：

BANNERIFY_API_KEY=YOUR_OTHER_KEY bannerify create image tpl_xxx -o out.png

基底網址也遵循相同的順序：--base-url 旗標、BANNERIFY_BASE_URL 環境變數、已儲存的設定，最後是 https://api.bannerify.co/v1。

設定檔

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

請用 config 指令變更設定檔。CLI 指令列出了這些指令。

用量與限制

從 CLI 生成的檔案，與 REST API 和 SDK 計入相同的每月與每日上限。失敗的請求不會計算。詳情請見用量額度與限制。