CLI Tool

Use banana-cli to operate Banana Slides from the command line

Overview

banana-cli is the command-line tool for Banana Slides, implementing all features through the backend REST API. Ideal for:

• Batch generation: Create PPTs in bulk from JSONL/CSV files
• Automation pipelines: Integrate into CI/CD or scripts
• AI Agent orchestration: Use as a tool-calling interface for agents

Installation

From the project root:

uv sync          # Install dependencies
uv run banana-cli --help  # Verify installation

Agent Skill

If you use AI Agents in Claude Code, install the banana-cli skill with a single command so the Agent automatically knows how to use the CLI:

# Global install (recommended, available in all projects)
npx skills add Anionex/banana-slides -g

# Or install to current project only
npx skills add Anionex/banana-slides

Once installed, the Agent will invoke /banana-cli as needed, with full environment detection, setup guidance, and usage examples.

Global Options

All commands support the following global options:

banana-cli [global-options] <command-group> <subcommand> [options]

Option	Description	Default
--base-url	Backend address	http://localhost:5011
--access-code	Access code (injected as X-Access-Code header)	None
--poll-interval	Task polling interval (seconds)	3
--request-timeout	Request timeout (seconds)	60
--config	Config file path (TOML)	~/.config/banana-slides/cli.toml
--json	Output in JSON format	Off
--verbose	Verbose output	Off

Configuration Priority

CLI args > Environment variables (BANANA_CLI_*) > TOML config file > Defaults

Environment variable mapping:

BANANA_CLI_BASE_URL=http://localhost:5011
BANANA_CLI_ACCESS_CODE=your-code
BANANA_CLI_POLL_INTERVAL=3
BANANA_CLI_REQUEST_TIMEOUT=60
BANANA_CLI_CONTINUE_ON_ERROR=true

---

Short ID Prefix Matching

All --project-id and --page-id parameters accept short prefixes (like git short hashes) instead of full UUIDs:

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

The prefix must uniquely match one project/page. If multiple matches are found, you’ll be prompted to provide more characters.

Working Project Context

Set a working project to skip --project-id on subsequent commands:

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

The working project is stored in ~/.config/banana-slides/context.json and persists across sessions.

---

Command Reference

projects — Project Management

# List projects
banana-cli projects list --limit 50 --offset 0

# Get project details
banana-cli projects get <project_id>

# Create project
banana-cli projects create --creation-type idea --idea-prompt "AI technology trends"

# Update project
banana-cli projects update <project_id> --template-style "Dark business style"

# Delete project
banana-cli projects delete <project_id>

# Set/show working project
banana-cli projects use <project_id>
banana-cli projects use

# Clear working project
banana-cli projects unuse

workflows — Workflows

End-to-end PPT generation pipeline.

# Generate outline
banana-cli workflows outline --project-id <id>

# Specify page count (hint to AI, actual count may differ)
banana-cli workflows outline --project-id <id> --pages 8

# Generate outline from descriptions
banana-cli workflows outline --project-id <id> --from-description

# Refine outline with natural language
banana-cli workflows outline --project-id <id> --refine "Add a page about market analysis"

# Generate descriptions (waits for completion by default; add --no-wait for async)
banana-cli workflows descriptions --project-id <id>

# Generate images
banana-cli workflows images --project-id <id> --use-template

# Full pipeline: outline -> descriptions -> images
banana-cli workflows full --project-id <id> --language zh

# Full pipeline with page count (page count is a hint to AI, actual count may differ)
banana-cli workflows full --project-id <id> --language zh --pages 10

workflows full supports skipping steps:

banana-cli workflows full --project-id <id> \
  --skip-outline \
  --desc-max-workers 4 \
  --image-max-workers 2

pages — Page Operations

# Create page
banana-cli pages create --project-id <id> --order-index 0

# Set outline content
banana-cli pages set-outline --project-id <id> --page-id <pid> \
  --outline-json '{"title": "Chapter 1"}'

# Generate single page description
banana-cli pages gen-description --project-id <id> --page-id <pid>

# Generate single page image
banana-cli pages gen-image --project-id <id> --page-id <pid> --use-template

# Edit image
banana-cli pages edit-image --project-id <id> --page-id <pid> \
  --instruction "Change the title to red"

# View image versions
banana-cli pages versions --project-id <id> --page-id <pid>

# Switch image version
banana-cli pages set-current --project-id <id> --page-id <pid> --version-id <vid>

exports — Export

# Export PPTX (returns download URL)
banana-cli exports pptx --project-id <id>

# Export and download locally
banana-cli exports pptx --project-id <id> --output ./slides.pptx

# Export PDF
banana-cli exports pdf --project-id <id> --output ./slides.pdf

# Export images
banana-cli exports images --project-id <id>

# Export editable PPTX (waits for completion by default)
banana-cli exports editable-pptx --project-id <id> --output ./editable.pptx --max-depth 2

--output specifies a local download path; if omitted, the server-side download URL is returned. --filename only sets the filename generated on the server side.

materials — Material Management

# Upload material to project
banana-cli materials upload --file /path/to/image.png --project-id <id>

# Upload global material
banana-cli materials upload --file /path/to/image.png --global

# AI-generate material
banana-cli materials generate --prompt "Tech-style background" --project-id <id> --wait

# Associate global material with project
banana-cli materials associate --project-id <id> --material-url <url>

# Download material
banana-cli materials download --material-id <mid> --output /tmp/materials.zip

refs — Reference Files

# Upload reference file
banana-cli refs upload --file /path/to/document.pdf --project-id <id>

# Trigger parsing
banana-cli refs parse --file-id <fid>

# Associate with project
banana-cli refs associate --file-id <fid> --project-id <id>

templates — Templates

# Upload template image
banana-cli templates upload --project-id <id> --file /path/to/template.png

# Delete template
banana-cli templates delete --project-id <id>

renovation — PPT Renovation

# Upload old PPT for renovation
banana-cli renovation create --file /path/to/old.pptx --wait --language zh

settings — Settings

# Get current settings
banana-cli settings get

# Update settings
banana-cli settings update --data '{"TEXT_MODEL": "gemini-2.0-flash"}'

# Reset settings
banana-cli settings reset

# Verify configuration
banana-cli settings verify

# Run feature test
banana-cli settings test --name text-model

tasks — Task Status

# Query task status
banana-cli tasks status --project-id <id> --task-id <tid>

# Wait for task completion (shows real-time progress)
banana-cli tasks wait --project-id <id> --task-id <tid> --timeout-sec 600

tasks wait can be interrupted with Ctrl+C and resumed at any time — the backend task is not affected.

styles — Style Extraction

banana-cli styles extract --image /path/to/reference.png

files — File Download

banana-cli files fetch --url /files/project-id/exports/slides.pptx --output ./slides.pptx

---

Batch Jobs

Job File Format

Supports JSONL and CSV formats. Each line defines one generation task.

JSONL example (jobs.jsonl):

{"job_id":"job-1","job_type":"full_generation","creation_type":"idea","idea_prompt":"Introduction to AI","language":"en","export":{"formats":["pptx"]}}
{"job_id":"job-2","job_type":"full_generation","creation_type":"idea","idea_prompt":"Machine Learning in Practice","language":"en","export":{"formats":["pptx","pdf"]}}

Field descriptions:

Field	Required	Description
job_id	No	Job identifier for tracking and deduplication
job_type	Yes	full_generation or export_only
creation_type	Yes*	idea, outline, or descriptions (required for full_generation)
idea_prompt	Yes*	Topic description (required when creation_type=idea)
language	No	zh, en, ja, auto
use_template	No	Whether to use template for image generation, default true
export.formats	Yes	Export format list: pptx, pdf, images, editable_pptx
reference_files	No	List of absolute paths to reference files
material_files	No	List of absolute paths to material files
template_image_path	No	Absolute path to template image

Running Batch Jobs

banana-cli run jobs \
  --file jobs.jsonl \
  --report report.json \
  --continue-on-error \
  --timeout-sec 3600 \
  --state-file state.json \
  --done-marker-file done.json

• --state-file: Writes running state in real-time for monitoring
• --done-marker-file: Records completed jobs; automatically skipped on re-run
• --continue-on-error / --fail-fast: Continue after failure or stop immediately

Monitoring Run Status

# View a single snapshot
banana-cli run monitor --state-file state.json

# Continuous monitoring until completion
banana-cli run monitor --state-file state.json --watch --interval 30

Interactive Job File Builder

uv run python -m cli.banana_cli.jobs.interactive_builder --output jobs.jsonl --count 3

---

Typical Workflow Examples

From Idea to PPTX

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

# 2. Full generation (working project is set, no --project-id needed)
banana-cli workflows full --language zh --pages 8

# 3. Export locally
banana-cli exports pptx --output ./report.pptx

Batch Generate 10 PPTs

# Prepare job file
cat > batch.jsonl << 'EOF'
{"job_id":"ai-intro","job_type":"full_generation","creation_type":"idea","idea_prompt":"AI Beginner's Guide","language":"en","export":{"formats":["pptx"]}}
{"job_id":"ml-guide","job_type":"full_generation","creation_type":"idea","idea_prompt":"Machine Learning in Practice","language":"en","export":{"formats":["pptx"]}}
EOF

# Execute
banana-cli run jobs --file batch.jsonl --report report.json --state-file state.json

---

Notes

1. Backend must be running: The CLI calls the backend API over HTTP — ensure the backend is started before use
2. File paths must be absolute: All --file, --image parameters require absolute paths
3. Waits for completion by default: Async tasks such as description generation, image generation, and editable export wait for completion and show progress by default. Pass --no-wait to return the task_id immediately, then use tasks wait to poll manually
4. Interruptible and resumable: --wait and tasks wait can be interrupted with Ctrl+C at any time. The backend task is unaffected — you can resume waiting with the same task_id
5. --pages is a hint: --pages is passed as a hint to the AI; the actual number of generated pages may differ. When there is a mismatch, the CLI prints a notice to stderr
6. Progress output: While waiting for a task, progress information is written to stderr (format: [PROGRESS] stage status completed/total) and does not interfere with JSON output on stdout
7. Shell completion: Run banana-cli --install-completion to install auto-completion for your current shell
8. AI Agent friendly: When stdout is piped (non-TTY), --help automatically outputs plain text without Rich formatting