fotohubapp-cli

Official command-line interface for the FOTOhub AI Platform. A full interactive agent in your terminal — generate images, video, 3D, music and speech, chat with 30+ LLMs, connect MCP servers, and manage cloud storage. Scriptable for automation, interactive for exploration.

npm install -g fotohubapp-cli

Requires Node.js 20+.

Two ways to use it

Interactive agent — just run fotohub with no arguments in a terminal:

fotohub

You get a streaming chat UI where the assistant can call FOTOhub tools (generate an image, check your balance, list buckets…) and any MCP servers you've connected — the tool calls and their results render inline as they happen.

Scriptable commands — every capability is also a plain subcommand with machine-readable --json output, so it drops straight into pipelines and CI:

fotohub generate image "a futuristic city at sunset" --json | jq -r '.url'

Quick Start

# 1. Authenticate (stores your key in the OS keychain)
fotohub auth login

# 2. Generate an image
fotohub generate image "a futuristic city at sunset"

# 3. Launch the interactive agent
fotohub

# 4. Check your balance
fotohub billing balance

Commands

Authentication

fotohub auth login              # Store your API key securely
fotohub auth logout             # Remove stored credentials
fotohub auth whoami             # Show account info
fotohub auth keys list          # List API keys
fotohub auth keys create        # Create a new key

AI Generation

fotohub generate image <prompt>   # Generate an image (25+ models)
fotohub generate video <prompt>   # Generate a video (Veo, Kling, Wan)
fotohub generate 3d               # Generate a 3D model (image- or text-to-3D)
fotohub generate music <prompt>   # Generate music
fotohub generate speech <text>    # Text-to-speech

Image options: --model, --width, --height, --num, --aspect-ratio, --negative-prompt, --seed, --output Video options: --model, --duration, --aspect-ratio, --image (image-to-video), --no-wait 3D options: --mode, --model, --file, --prompt, --format, --quality, --no-wait Music options: --model, --duration, --instrumental, --output

Async jobs (video, 3D) poll to completion by default. Pass --no-wait to get the job ID immediately and check status later.

Chat & the interactive agent

fotohub                           # Interactive agent (streaming, tool use, MCP)
fotohub chat                      # Streaming chat REPL
fotohub chat send "Hello"         # One-shot message

Supports 30+ models from 12 providers: Claude, GPT, Grok, DeepSeek, Gemini, Qwen, Nova, Mistral, Kimi, and more.

Chat options: --model, --system, --temperature Interactive slash commands: /model, /system, /mcp, /whoami, /clear, /quit

MCP (Model Context Protocol)

The CLI is a full MCP client, a one-command bridge to FOTOhub's own MCP server, and can expose itself as a local MCP server for Claude Desktop / Cursor.

fotohub mcp connect               # Connect to FOTOhub's MCP server with your key
fotohub mcp add <name> --url <url>        # Add a remote (HTTP) MCP server
fotohub mcp add <name> --command <cmd>    # Add a local (stdio) MCP server
fotohub mcp list                  # List configured servers
fotohub mcp tools <name>          # List a server's tools
fotohub mcp remove <name>         # Remove a server
fotohub mcp serve                 # Expose this CLI as a local stdio MCP server

Tools from connected servers are automatically available to the interactive agent, namespaced as <server>__<tool>.

To use the CLI as an MCP server in Claude Desktop, add to its config:

{ "command": "fotohub", "args": ["mcp", "serve"] }

Models

fotohub models list               # List all available models
fotohub models list --category image
fotohub models list --provider anthropic
fotohub models info <model-id>    # Model details & pricing

Cloud Storage (S3)

fotohub storage list              # List buckets
fotohub storage create <name>     # Create a bucket
fotohub storage upload <file> -b <bucket>   # Upload a file
fotohub storage download <key> -b <bucket>  # Download a file
fotohub storage ls <bucket>       # List objects

Billing & Usage

fotohub billing balance           # Credits & wallet balance
fotohub billing usage             # Usage breakdown
fotohub billing history           # Transaction history

Workflows

fotohub workflow list             # List workflows
fotohub workflow run <id>         # Execute a workflow
fotohub workflow status <exec-id> # Check execution status

Configuration & system

fotohub config list               # Show all config
fotohub config set <key> <value>  # Set a value
fotohub config get <key>          # Get a value
fotohub status                    # System health check
fotohub --version                 # CLI version

Global Options

| Flag | Description | |------|-------------| | --api-key <key> | Override stored API key for this invocation | | --json | Output raw JSON (machine-readable) | | --no-color | Disable colored output | | --base-url <url> | Custom API endpoint | | --verbose | Debug output |

Credentials & Security

Your API key is stored in the operating-system keychain (macOS Keychain, Windows Credential Manager, Linux libsecret). Where no keychain is available — headless Linux, containers — the CLI transparently falls back to an AES-256-GCM encrypted file at ~/.fotohub/creds.enc (permissions 0600), with the key derived via scrypt from a machine-bound salt. Set FOTOHUB_CRED_PASSPHRASE to require a passphrase on top of the machine binding.

Auth priority: --api-key flag > FOTOHUB_API_KEY env var > keychain > encrypted file > legacy config.json (migrated on first use).

A legacy plaintext ~/.fotohub/config.json key from older versions is migrated into secure storage automatically the first time you run v2.2, and the plaintext value is removed.

Environment Variables

| Variable | Description | |----------|-------------| | FOTOHUB_API_KEY | API key (alternative to fotohub auth login) | | FOTOHUB_BASE_URL | Custom API endpoint | | FOTOHUB_CRED_PASSPHRASE | Passphrase for the encrypted-file credential fallback | | NO_COLOR | Disable colors (standard) |

Examples

# Generate 4 images with a specific model, save the first
fotohub generate image "abstract art" --model flux-schnell --num 4 --output art.png

# Image-to-video, return the job ID immediately
fotohub generate video "camera slowly zooms in" --image https://example.com/photo.jpg --duration 10 --no-wait

# Chat with a system prompt
fotohub chat send "Explain quantum physics simply" --system "You are a physics teacher"

# JSON output for scripting
fotohub models list --json | jq '.[] | select(.category == "image") | .id'

# Upload a file to storage
fotohub storage upload ./render.mp4 -b my-renders

# Run a workflow with input
fotohub workflow run abc123 --input '{"prompt": "hello"}'

Documentation

Full guide and API reference: docs.fotohub.app/guides/cli-setup

License

MIT