obra - Multi-Provider Creative AI CLI

A command-line tool for generating images, videos, and music using AI providers like Kie.ai.

Installation

npm install -g obra

Set Up Your API Key

Obra currently uses Kie.ai as its AI provider. Sign up for an account and grab your API key from https://kie.ai/api-key, then configure it:

obra config set kie.apiKey YOUR_API_KEY

Verify it's set:

obra config list

Your config is stored at ~/.config/obra/config.json (or run obra config path to see the exact location).

Generating Content

Basic Usage

All generation commands follow the same pattern:

obra <type> generate "<prompt>" [options]

Model-specific parameters are passed with --param:

obra <type> generate "<prompt>" --param key=value --param key2=value2

Without --wait, the command returns immediately with a task ID. With --wait, it polls until complete and shows the result URL.

Image Generation

# Start a task (returns task ID immediately)
obra image generate "a red panda eating bamboo"

# Wait for completion and get the result URL
obra image generate "a red panda eating bamboo" --wait

# With model and parameters
obra image generate "cyberpunk cityscape" \
  --model google/imagen4-fast \
  --param aspect_ratio=16:9 \
  --wait

# Multiple parameters
obra image generate "portrait photo" \
  --model qwen/text-to-image \
  --param image_size=portrait_16_9 \
  --param guidance_scale=5.0 \
  --param seed=42 \
  --wait

Video Generation

obra video generate "ocean waves crashing on rocks" \
  --param duration=5 \
  --param aspect_ratio=16:9 \
  --wait

# Image-to-video (animate a reference image)
obra video generate "make it come alive" \
  --image ./my-photo.png \
  --wait

Music Generation

# With vocals
obra music generate "upbeat pop song about summer" --wait

# Instrumental only
obra music generate "lo-fi hip hop beats" --instrumental --wait

# With custom lyrics
obra music generate "acoustic ballad" \
  --lyrics "Here are my custom lyrics..." \
  --wait

Finding Your Generated Assets

Note: The generate command does not automatically download files. It returns a URL where your content is hosted. Use obra download to save files locally.

Step 1: Generate and Get the URL

When you add --wait, the CLI waits for completion and displays the result URL:

$ obra image generate "a mountain sunset" --wait

✓ Task created: abc123
⠋ Generating image... 100%

Task Result:
  ID: abc123
  Status: success

Outputs:
  • https://cdn.kie.ai/outputs/abc123/image.png

You can open this URL directly in your browser, or continue to step 2 to download.

Step 2: Download to Your Computer

Use the task ID to download the file:

# Download to current directory
obra download abc123

# Download to specific directory
obra download abc123 --output ./my-images/

The file will be saved as abc123_1.png (or similar based on content type).

If You Didn't Use --wait

Check the task status later using the task ID:

# Check current status
obra status abc123

# Wait for completion and show URL
obra status abc123 --wait

# Then download
obra download abc123

JSON Output

For scripting, use --json to get machine-readable output:

obra image generate "a cat" --wait --json

Output:

{
  "id": "abc123",
  "status": "success",
  "outputs": [
    {
      "url": "https://cdn.kie.ai/outputs/abc123/image.png",
      "type": "image"
    }
  ]
}

Generation History

Obra automatically tracks your generations locally.

# List recent generations
obra history list

# Filter by type or status
obra history list --type image --status success

# Show fewer/more entries (default: 20)
obra history list --limit 5

# Show details for a specific entry (by row number or task ID)
obra history show 3
obra history show abc123

# Clear all history
obra history clear --yes

# Show where history is stored
obra history path

Discovering Models & Parameters

Each model has different parameters. Use info to see what's available:

# List all image models
obra image list

# Get details and parameters for a specific model
obra image info qwen/text-to-image

# Same for other types
obra video list
obra video info grok-imagine/text-to-video
obra music list
obra music info V4_5

The info command shows all available parameters and how to pass them with --param.

Configuration

View Configuration

obra config list              # Show all settings
obra config path              # Show config file location
obra config get kie.apiKey    # Get a specific value (masked)

Modify Configuration

# Set API key
obra config set kie.apiKey YOUR_API_KEY

# Change default image model
obra config set defaults.image.model google/imagen4-fast

# Reset everything to defaults
obra config reset -y

Default Models

| Type | Default Model | |-------|--------------------------------| | Image | flux-2/pro-text-to-image | | Video | grok-imagine/text-to-video | | Music | V4_5 |

Provider Management

# List available providers
obra provider list

# Show provider details
obra provider info kie

# Switch default provider (for future multi-provider support)
obra provider use kie

Command Reference

| Command | Description | |---------|-------------| | obra image generate <prompt> | Generate an image | | obra video generate <prompt> | Generate a video | | obra music generate <prompt> | Generate music | | obra music lyrics <prompt> | Generate lyrics only | | obra status <id> | Check task status | | obra download <id> | Download task outputs | | obra image list | List available image models | | obra image info <model> | Show image model details and parameters | | obra video list | List available video models | | obra video info <model> | Show video model details and parameters | | obra music list | List available music models | | obra music info <model> | Show music model details and parameters | | obra history list | List recent generations | | obra history show <ref> | Show details of a history entry | | obra history clear | Clear all history | | obra config <subcommand> | Manage configuration | | obra provider <subcommand> | Manage providers |

Common Options

| Option | Description | |--------|-------------| | -w, --wait | Wait for task completion | | -o, --output <path> | Output file/directory | | -m, --model <name> | Model to use | | --param <key=value> | Model parameter (repeatable) | | --params-json <json> | Model parameters as JSON | | -p, --provider <name> | Provider to use | | --json | Output as JSON | | -h, --help | Show help |

Development

# Install dependencies
bun install

# Run in development mode
bun run bin/obra.ts [command]

# Build (compiles TypeScript to JavaScript)
npm run build

# Build standalone binary (requires Bun)
npm run build:binary

# Run tests
bun test

# Run tests in watch mode
bun test --watch

License

MIT