Brandly CLI

AI product video orchestrator — plan, generate, and publish professional product videos with AI. Works from the terminal, or from any AI assistant (OpenCode, Codex, Qwen Code, Claude Code, Cursor, …) through agent tools and an MCP server.

What is Brandly?

Brandly turns a product idea into a finished video. You describe the product; Brandly plans the shots, generates the footage, checks the quality, and exports it for the platforms you want — TikTok, Instagram, YouTube, or a plain MP4.

Everything runs from one command, brandly, with 83 commands behind it. You never have to use all of them: the quick start below uses five.

What you can do

Who is it for?

• Marketers and creators — make product videos without a production team
• Developers — drive video generation from your own apps or agents (CLI, agent tools, MCP server)
• AI enthusiasts — orchestrate image + video + audio models in one workflow

Quick start (5 minutes)

1. Install

pip install brandly-cli

2. Get an API key

1. Sign up at Agnes AI
2. Copy your API key
3. Set it as an environment variable:

export AGNES_API_KEY="your_key_here"
# add to ~/.bashrc or ~/.zshrc to make it permanent

Or let Brandly sync your existing AI-tool configs automatically:

brandly sync

3. Create your first project

brandly init -n "My Product" -i "A sleek wireless charger that doubles as a desk lamp"

That's it — one command, one idea. Add -s cinematic for a cinematic style or -b 200 to set a credit budget when you're ready for more control.

4. Run the pipeline

# let the pipeline run phase by phase (stops for your approval at human gates)
brandly run <project_id> --execute --until publish

Or run it one phase at a time — script writes the shot list, asset generates the shots, validate checks quality, publish exports.

5. See the results

brandly timeline <project_id>   # visual timeline editor in your browser
brandly status <project_id>     # text status: what exists, what's next

How it works

Brandly runs your project through a fixed sequence of phases. Each phase has a clear job, and each one refuses to continue on failure — so a broken step never quietly produces bad footage downstream.

init → trends → concept → script → asset → audio → re_edit → validate → publish

You approve at the gates (brandly approve <id> <phase>); Brandly handles the rest. Everything it does is visible: brandly plan <id> --json shows each phase's inputs and outputs, brandly cost <id> shows what was spent, brandly scenes <id> shows the shot manifest.

Two ways to work

Creators: you drive, step by step

brandly init -n "Product Name" -i "Brief description" -s cinematic
brandly status <id>            # review the plan
brandly approve <id> script    # approve the shot list
brandly run <id> --execute --until asset     # generate shots (resumable)
brandly gate <id> --all-scenes               # quality check
brandly run <id> --execute --until publish   # assemble & export

Driving brandly from an AI tool

Brandly exposes 22 agent-callable tools through its MCP server — the same operations as the CLI, packaged for AI tools:

brandly mcp serve              # start the MCP server
brandly tools --json           # list all 22 tools with read-only flags
brandly tools call produce --project_id <id> --shots 5

Ten tools are read-only (safe for an agent to call without asking): list_projects, get_project, list_jobs, list_models, get_timeline, run_gate, plan, status, progress, estimate. Twelve write state — including approve, which stays a human gate on purpose: an AI can ask for approval, but a person decides.

For a full walkthrough of driving Brandly from an AI tool:

brandly director               # print the Director prompt for your AI tool

Command cheat sheet

83 commands, grouped by what you're trying to do. Run brandly <command> --help for any of them.

Projects

brandly init -n "Name" -i "Idea" -s cinematic -b 500   # new project
brandly list                                           # all projects
brandly status <id>                                    # what exists, what's next
brandly pause <id> / brandly resume <id>               # pause and resume
brandly cancel <id>                                    # cancel a project
brandly template / brandly template-list               # reusable project templates

The pipeline

brandly run <id> --execute --until produce             # run phase by phase
brandly run <id> --execute --only shot-03 shot-07      # regenerate specific shots
brandly approve <id> <phase>                           # human gate approval
brandly plan <id> --json                               # phase contracts: inputs/outputs
brandly scenes <id> --json                             # the shot manifest
brandly script <id>                                    # validate beat completeness
brandly produce <id> --shots shots.json --interval 60  # manual shot-by-shot run

Generation

brandly video <id> -p "prompt" --style commercial      # single video clip
brandly image <id> -p "prompt"                         # single image
brandly reference <id>                                 # the primary reference image
brandly music <id>                                     # background music
brandly tts <id>                                       # voiceover
brandly batch <id>                                     # variants of a base prompt
brandly storyboard <id>                                # keyframes for each shot
brandly ark-video / minimax-video                      # other providers

Quality

brandly gate <id> --all-scenes                         # all scenes, checked
brandly gate <id> --element ./clip.mp4 --ref ./ref.png # one element vs its reference
brandly gate-drift <id>                                # cross-shot prompt drift check
brandly validate <id>                                  # virality scoring
brandly analyze <id> / brandly analyze-project <id>    # performance prediction

Post-production

brandly assemble <id>                                  # assemble the final film
brandly stitch c1.mp4 c2.mp4 --output final.mp4        # stitch clips
brandly captions <id>                                  # burned-in subtitles
brandly beat-sync <video> <music>                      # cut to the beat
brandly voice-match <video> --target es                # dub to another language
brandly mux <video>                                    # mix narration/music into a video
brandly thumbnail <id> --style cinematic               # thumbnails

Export & publish

brandly export <id> --platforms tiktok,instagram,youtube   # platform renders
brandly export-platforms <id>                              # 9:16 / 1:1 / 16:9 formats
brandly publish <id> --dry-run                             # preview the posts
brandly publish <id> --platforms tiktok,instagram          # schedule them
brandly config set tiktok <token>                          # store credentials
brandly share <id>                                         # upload to cloud for sharing

Money & limits

brandly estimate --style cinematic --shots 8           # cost before you start
brandly estimate --target-duration 120                 # quota-aware plan (warns + multi-day split)
brandly cost <id> --breakdown                          # what each phase spent
brandly record-cost <id> --phase asset --credits 40    # record actual spend
brandly rate-limits                                    # provider rate limits
brandly models / brandly model <name>                  # what models are available

Media utilities

brandly probe <video>          # video metadata
brandly resize <video>         # resize / change aspect ratio
brandly speed <video>          # playback speed
brandly edit <video>           # trim to a segment
brandly concat a.mp4 b.mp4     # concatenate
brandly audio <video>          # extract the audio track
brandly optimize-refs <img>    # split a large reference into small + HQ pair

Tools & integration

brandly mcp serve              # MCP server for AI tools
brandly tools --json           # the 22-tool agent surface
brandly director               # the Director prompt
brandly capabilities           # capability map per persona
brandly sync                   # auto-detect AI-tool configs
brandly webhook                # webhook server for CI/CD
brandly team                   # multi-user collaboration
brandly report                 # report a bug or request a feature

Built-in safety

Brandly is designed to fail loudly and spend carefully:

• Human gates — the pipeline stops at phase boundaries for your approval. approve is always a person's decision.
• Fail-closed phases — a failed step freezes the pipeline and exits non-zero; nothing downstream continues on broken input.
• Measured truth — every returned clip is measured against what was requested. A 5-second take for a 12-second request is never silently marked OK: it triggers a continuation take, or ships honestly marked short.
• Cost awareness — brandly estimate previews the credit cost before you start; quota warnings propose a multi-day schedule when a plan would exceed your daily limit.
• Fail-honest quality — when a quality check couldn't actually run (no API key, AI unavailable), results are marked UNVERIFIED — never passed as verified.
• Dry-run publishing — brandly publish --dry-run shows exactly what would be posted before anything is scheduled.
• Credentials stay local — provider tokens live in your local config, never in the project or the repo.

Styles & references

Styles

Reference images (consistency across shots)

Register your character and product references once, and every shot stays consistent:

brandly reference <id> --image char.png --subject-type character
brandly reference <id> --image prop.png --subject-type prop

For keyframe-controlled clips (start and end frames fixed):

brandly video <id> -p "transition" --mode keyframe --first-frame start.png --last-frame end.png

Monitoring & debugging

brandly status <id>            # project dashboard
brandly progress <id>          # detailed phase progress
brandly cost <id> --breakdown  # spending
brandly rate-limits            # provider rate limits & daily quota
brandly jobs                   # recent API jobs
brandly job-resume <video_id>  # recover a crashed job
brandly job-poll <video_id>    # poll a job to completion
brandly timeline <id> --port 8765   # visual editor
brandly metrics                # platform metrics ingest
brandly brand <id>             # brand-kit enforcement (logo/colour/claim lock)

Configuration

brandly config show            # view current config
brandly config set tiktok "access_token=..."
brandly config set instagram "access_token=..."
brandly config set youtube "client_id=... client_secret=..."
brandly memory show            # your preferences (budget, defaults)

Environment variables:

export AGNES_API_KEY="..."          # required for Agnes video/image
export BRANDLY_IMAGE_CONVERT=off    # disable automatic image compression
export BRANDLY_WEB_PORT=8765        # timeline editor port

For developers

.brandly/<project>/
├── project.json        # product, style, budget, phase state
├── shots.json          # canonical shot list (produce + gate-drift resolve this)
├── cost.json           # per-phase spend
├── scenes.json         # scene manifest with beats and durations
├── docs/plan/          # trends.md, concept.md
├── pre-production/     # reference plates, storyboards
└── production/         # clips, audio, final.mp4

from brandly_cli.video_backend import VideoBackend, VideoBackendCapabilities

class MyBackend(VideoBackend):
    def capabilities(self) -> VideoBackendCapabilities: ...
    async def submit(self, ...) -> ...: ...
    async def poll(self, ...) -> ...: ...
    async def fetch(self, ...) -> ...: ...

Demos

Producer videos: F1tr08UeHLs · 7lNt1Y8tAzo

Roadmap

• ✅ Publish/schedule — supported via brandly publish (dry-run, multi-platform posts, stored credentials)
• ✅ Quality gates — per-scene and element checks via brandly gate
• ✅ Studio shell — visual timeline editor via brandly timeline
• ✅ Agent surface — 22 tools via MCP (brandly tools --json)
• ✅ Document chain — trends → concept → script is a real, fail-closed chain
• ⏳ Additional video backends — the VideoBackend seam is ready; more providers welcome

Development

pip install -e ".[dev]"       # dev dependencies
make test                     # full suite (Python + web contracts)
make lint                     # ruff + oxlint + mypy + import-linter
cd web && npm run dev         # web UI development
pip wheel . -w dist/          # build the wheel

Pipeline governance: AUDIT-AGENTIC-PIPELINE.md is the single source of truth for open gaps.

Star this repo

If Brandly helps you create better product videos, please consider starring the repository on GitHub — it helps others discover the project and motivates continued development.

License

MIT — Dream Pixels Forge