Skip to content

cli.md

Latest commit

 

History

History
140 lines (97 loc) · 3.71 KB

cli.md

File metadata and controls

140 lines (97 loc) · 3.71 KB

OpenLoop CLI Guide

openloop comes with a built-in CLI — the same binary as the desktop app. When you pass a subcommand, it runs headlessly. No separate install.

Commands

openloop run

Generate music from a prompt.

openloop run "lo-fi warm piano, 90 BPM"
openloop run --model pro --duration 30 --output ~/Music/beat.mp3
openloop run "epic cinematic" --json            # machine-readable output
Flag Short Description
--model -m Model variant: lite, turbo, pro
--duration -d Duration in seconds (10–600)
--format -f Output format: wav, mp3, flac, ogg
--output -o Output file path
--lyrics -l Lyrics text with optional [verse]/[chorus] tags
--bpm BPM (30–300)
--key Key and scale (e.g. C major)
--seed Random seed for reproducibility
--variations -v Number of variations (1–4)
--no-thinking Disable thinking mode
--json Stream NDJSON progress events to stdout

openloop setup

Configure default generation settings.

openloop setup                   # interactive wizard (in a terminal)
openloop setup model turbo       # set individual values
openloop setup duration 60
openloop setup --json            # show current settings as JSON

Keys: model (lite/turbo/pro), thinking (on/off), duration (10–600), format (wav/mp3/flac/ogg)

openloop list

Show generation history.

openloop list                    # last 20 records
openloop list --limit 5          # last 5
openloop list --json             # JSON output

openloop pull

Download a model variant before generating.

openloop pull turbo
openloop pull pro

openloop models

List available models and their download status.

openloop models
openloop models --json

openloop ps

Show backend process status and active generation tasks.

openloop ps
openloop ps --json

openloop delete

Delete a generation record and its output file.

openloop delete a1b2c3d4        # full or partial ID from `openloop list`

openloop clear

Delete all generation history and output files.

openloop clear                   # prompts for confirmation
openloop clear --yes             # skip confirmation

openloop stop

Stop the ACE-Step backend process.

openloop stop

Agent Pipelines

openloop is designed for AI coding agents to compose with. Paired with Remotion (programmatic React video rendering) or HyperFrames (HTML-to-video for agents), an agent can build fully automated video workflows.

An agent would typically:

  1. Call openloop run "cinematic strings" --json and parse the streaming output
  2. Take the output_path from the completed event
  3. Feed it into a Remotion composition or HyperFrames render
# Agent workflow
openloop run "cinematic strings" --duration 120 --format mp3 --output ./assets/bg.mp3 --json
openloop models --json
openloop ps --json

The --json flag streams one JSON object per line — agents can parse progress line by line:

{"event":"running","variation":1,"total":1}
{"event":"completed","output_path":"/abs/path/track.wav","duration":30.0,"format":"wav"}

On error:

{"event":"failed","error":"backend health timeout after 60s"}

All commands return exit code 0 on success, 1 on error.

PATH Setup

If you installed via DMG, open OpenLoop → Settings → "Add to PATH" to enable the openloop CLI command from any terminal. Homebrew cask installs handle this automatically.