ターミナルから生成する

Bannerify CLI は、ターミナルから画像と PDF を生成します。REST API と同じテンプレートと API キーを使うので、1 つのコマンドでファイルを描画し、その結果を別のツールに渡せます。このページは、シェルで作業する開発者と、シェルを呼び出すスクリプトやエージェントを対象にしています。

CLI は、次のような場面で使います。

• ビルド、デプロイ、cron ジョブの中でファイルを描画する。
• シェルスクリプトから、多数の描画を実行する。
• コードを書かずに、エージェントやスクリプトでファイルを作成する。

始める前に

• テンプレートが 1 つ以上ある 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 -

スクリプト向けの JSON 出力と終了コードは、CLI コマンドで説明しています。

キーの解決順序

CLI は、次の順序で API キーを探します。

1. --api-key フラグ。
2. BANNERIFY_API_KEY 環境変数。
3. 保存済みの設定。

設定に 1 つのキーを保存しておき、1 回のコマンドやコンテナでだけ別のキーに上書きできます。

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

ベース URL も同じ順序で決まります。--base-url フラグ、BANNERIFY_BASE_URL 環境変数、保存済みの設定、最後に https://api.bannerify.co/v1 です。

設定ファイル

キー	用途
apiKey	CLI が送信する API キー
baseUrl	API のベース URL。初期値は https://api.bannerify.co/v1 です
defaultFormat	--format がないときの画像形式。初期値は png です
outputDir	--out がないときの、出力ファイルのフォルダー

ファイルは、config コマンドで変更します。コマンドの一覧はCLI コマンドにあります。

使用量と制限

CLI での生成は、REST API や SDK と同じ月間・日次の上限に含まれます。失敗したリクエストは数えられません。詳しくはクォータと制限を参照してください。

次のステップ

• CLI コマンド
• 画像の作成
• MCP クライアントを接続する