CLI コマンド

Bannerify CLI には、config、create、whoami の 3 つのコマンドがあります。

bannerify <command> [options]

コマンドのオプションを表示するには、bannerify --help または bannerify <command> --help を実行します。キーが保存されておらず、ターミナルが対話型の場合は、引数なしで bannerify を実行するとガイド付きのセットアップが始まります。それ以外の場合は、ヘルプが表示されます。

グローバルフラグ

フラグ	説明
-v, --version	CLI のバージョンを表示します
-h, --help	ヘルプを表示します。すべてのサブコマンドで使えます

config

CLI が実行の合間に保持する設定を管理します。コマンドは git config と同じように動作します。

コマンド	説明
bannerify config set <key> [value]	値を保存します。value を省略すると、対話型のターミナルでは入力を求め、スクリプトでは失敗します
bannerify config get <key>	値を 1 つ表示します
bannerify config list	保存されているすべての値を表示します
bannerify config delete <key>	値を削除します。値が設定されていない場合は、終了コード 1 で終了します

キー

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

CLI は、値を保存するときに検証しません。png、jpeg、webp 以外の defaultFormat は、あとで 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 のベース URL
--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 は 2 つの配列を、ファイルを先にして連結します。

存在しないレイヤー名はエラーなしで無視されます。値が変わらないときは、スペルを確認してください。レイヤーの種類ごとのフィールドは、Modificationsにまとめています。

例

# テキストを 1 つ上書きして 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 のベース URL を使います
--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 は次のオブジェクトを 1 つ表示します。

{
  "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 が返したエラーオブジェクトを表示し、0 以外の終了コードで終了します。

{
  "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	認証エラー。create は、エラーコードが 401、403、UNAUTHORIZED、FORBIDDEN のときに 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 出力は利用できません	3 つの形式のいずれかを使います
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 のようにリダイレクトします

関連情報

• ターミナルから生成する
• エラーの処理
• クォータと制限