banana-cli

banana-cli

AI 生成プレゼンテーションの作成、管理、エクスポートを行う CLI です。

環境の確認

コマンドを実行する前に、バックエンドに接続できることを確認してください。

curl -sf http://localhost:5011/health

失敗した場合、バックエンドは起動していません。references/setup.md を読み、手順に従ってリポジトリをクローンし、.env を設定して、バックエンドを起動してください。ヘルスチェックに合格するまで先に進まないでください。

実行方法

banana-cli <command> [options]

banana-cli が PATH にない場合は、プロジェクトのルートから uv run banana-cli を使うか、uv tool install . でグローバルにインストールしてください。

エンドツーエンドのワークフロー

# 1. Create project and set as working project
result=$(banana-cli --json projects create --creation-type idea --idea-prompt "Your topic")
project_id=$(echo "$result" | jq -r '.data.project_id')
banana-cli projects use "$project_id"

# 2. Generate everything (outline → descriptions → images)
banana-cli workflows full --language zh --pages 8

# 3. Export to local file
banana-cli exports pptx --output ./slides.pptx

作業対象のプロジェクトを設定すると、以降のすべてのコマンドで --project-id は省略できます。

主なパターン

短い ID のプレフィックスによる照合

すべての --project-id と --page-id は、Git の短縮ハッシュのような短いプレフィックスを受け付けます。

banana-cli projects get a1b2          # matches a1b2c3d4-...
banana-cli pages edit-image --page-id b9c8 --instruction "change title to red"

作業対象プロジェクトのコンテキスト

作業対象プロジェクトを設定すると、--project-id を繰り返し指定せずに済みます。

banana-cli projects use a1b2     # set (accepts prefix)
banana-cli workflows outline      # uses working project
banana-cli projects use           # show current
banana-cli projects unuse         # clear

ページ数の指定

--pages は AI への目安です。実際のページ数は異なる場合があります。一致しない場合、CLI は stderr に警告を出力します。

banana-cli workflows outline --pages 5
banana-cli workflows full --pages 10 --language en

自動ダウンロードによるエクスポート

# Download directly to local path
banana-cli exports pptx --output ./slides.pptx
banana-cli exports pdf --output ./report.pdf

# Without --output, returns a server-side download URL
banana-cli exports pptx

一括生成

cat > jobs.jsonl << 'EOF'
{"job_id":"t1","job_type":"full_generation","creation_type":"idea","idea_prompt":"AI Intro","language":"zh","export":{"formats":["pptx"]}}
{"job_id":"t2","job_type":"full_generation","creation_type":"idea","idea_prompt":"ML Basics","language":"zh","export":{"formats":["pptx","pdf"]}}
EOF

banana-cli run jobs --file jobs.jsonl --report report.json --state-file state.json

既存の PPT の刷新

banana-cli renovation create --file /absolute/path/to/slides.pptx --language zh

スクリプト向け JSON 出力

banana-cli --json projects list | jq '.data.projects[].project_id'

重要な注意事項

• ファイルパス引数（--file、--image）には絶対パスが必要です。
• 非同期タスク（説明、画像、編集可能なエクスポート）はデフォルトで完了まで待機し、stderr に進捗を表示します。すぐに task_id を取得するには --no-wait を渡してください。
• --wait / tasks wait は中断（Ctrl+C）して、いつでも再開できます。バックエンドのタスクには影響しません。
• 進捗行は stderr に出力されます（形式：[PROGRESS] STAGE STATUS completed/total）。これにより stdout の JSON はクリーンなまま保たれます。
• --help の出力はパイプに渡された場合（非 TTY）、プレーンテキストです。エージェントが安全に利用できます。
• 設定の優先順位：CLI 引数 > 環境変数（BANANA_CLI_*）> TOML 設定（~/.config/banana-slides/cli.toml）> デフォルト値

コマンドの確認

トップレベルのコマンド一覧を表示するには banana-cli --help を、サブコマンドのオプションを表示するには banana-cli <command> --help を実行してください。ヘルプ出力はパイプに渡された場合（非 TTY）、プレーンテキストです。