opusclip-cli

module

v0.1.0 Latest Latest Go to latest Published: Jun 19, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/tdeschamps/opusclip-cli

Links

Open Source Insights

README ¶

opusclip

A standalone CLI for the OpusClip API — submit a video, watch it render, download the clips. Scriptable, agent-friendly, and at home in any terminal.

_{Go Report Card, codecov, and the release/version badges activate once the repository is public.}

opusclip wraps the OpusClip API (https://api.opus.pro) behind one consistent interface, delivered as a single static binary. It turns long-form videos into short clips from the command line:

Creators / editors — clip a video URL and pull the results without opening the app.
Developers / integrators — script the create→render→download pipeline, pipe JSON, wire CI jobs.
AI / agent power users — drive clipping non-interactively with stable --json output and exit codes.

Design north star: feel like gh, stripe, and sentry-cli — predictable noun-verb commands, great --help, machine-readable output in pipes, human-readable in a TTY, first-class auth, and a stage-stepper for long-running renders.

Install

# Homebrew (macOS/Linux)
brew install tdeschamps/tap/opusclip

# Shell installer (downloads the latest signed release binary)
curl -fsSL https://raw.githubusercontent.com/tdeschamps/opusclip-cli/main/install.sh | sh

# From source (Go 1.25+)
go install github.com/tdeschamps/opusclip-cli/cmd/opusclip@latest

Prebuilt, signed binaries for darwin/{amd64,arm64}, linux/{amd64,arm64}, and windows/amd64 are attached to every release.

API access requires a qualifying OpusClip plan (Pro/Max/Enterprise, currently in beta). Get a key from the dashboard.

Quickstart

# 1. Authenticate (paste a key interactively, or pipe it in CI)
opusclip auth login                              # paste a key from clip.opus.pro/dashboard
echo "$OPUSCLIP_API_KEY" | opusclip auth login --with-token
opusclip auth status

# 2. Clip a video and block until the clips are ready
opusclip clip create --url "https://youtu.be/LXvv6CbGg8A" --wait

# 3. …or do it in steps and capture the project id
pid=$(opusclip clip create --url "https://youtu.be/LXvv6CbGg8A" --json --jq '.[0].projectId')
opusclip clip watch "$pid"                       # live stage stepper to COMPLETE

# 4. List and download the generated clips
opusclip clips list --project "$pid"
opusclip clips download --project "$pid" --out ./clips

# 5. Raw escape hatch — anything the typed commands don't cover yet
opusclip api GET /api/clip-projects/"$pid"

Commands

opusclip
├── auth        login | logout | status | switch | token
├── config      get | set | list | edit
├── profiles    list | use
├── clip        create | get | watch
├── clips       list | download
├── api         raw authenticated request escape hatch
├── info        version, configuration & status (logo banner)
├── doctor      connectivity & credential diagnostics
├── completion  bash | zsh | fish | powershell
├── docs        open the docs
├── update      self-update
└── version

clip create accepts a video --url plus optional curation flags (--genre, --lang, --keywords, --duration min:max, --start/--end, --brand-template) and conclusion actions (--webhook, --email). Add --wait to block until the render finishes.

Output & scripting

TTY → colorized, aligned tables. Piped/redirected → JSON.
Override anytime with -o table|json|csv|tsv|yaml or the --json shorthand.
Built-in --jq filter (powered by gojq; no external jq needed): opusclip clips list --project P1 --json --jq '.[].uriForExport'.
--columns id,title to pick/order columns for tables and CSV.
Long-running renders show a stage stepper on stderr; --wait/watch return a stable exit code by outcome (0 complete, 8 stalled, 124 timeout).

$ opusclip clips list --project P1
ID      TITLE          DURATION  GENRE    SCORE  CREATED
P1.c1   Best Moment    00:30     podcast  87     2026-06-17T10:05:00Z

$ opusclip clips list --project P1 --json --jq '.[].uriForExport'
https://storage.googleapis.com/...

Authentication

opusclip resolves the key in this order: --api-key/--token flag → OPUSCLIP_API_KEY/OPUSCLIP_TOKEN env → stored credential for the active profile. Secrets are stored in the OS keychain when available (macOS Keychain, Windows Credential Manager, libsecret/kwallet), with a 0600 file fallback. Set OPUSCLIP_NO_KEYRING to skip the keychain and persist to the 0600 file — handy in CI, headless shells, or on macOS where the keychain can pop an interactive prompt.

Keys are never printed back — opusclip auth status shows only a masked fingerprint. OpusClip authenticates with an API key only (no OAuth). Multi-org users can pass --org <id> or set OPUSCLIP_ORG_ID (sent as x-opus-org-id).

Configuration

Config lives at ~/.config/opusclip/config.toml (XDG-respecting; %APPDATA%\opusclip\config.toml on Windows). Any setting resolves flag → env var → profile → built-in default.

active_profile = "default"

[profiles.default]
base_url      = "https://api.opus.pro"
org_id        = ""
output        = "table"
default_limit = 50

Manage it with opusclip config get/set/list/edit and opusclip profiles list/use. Relevant env vars: OPUSCLIP_API_KEY, OPUSCLIP_TOKEN, OPUSCLIP_PROFILE, OPUSCLIP_BASE_URL, OPUSCLIP_ORG_ID, OPUSCLIP_OUTPUT, OPUSCLIP_NO_KEYRING, OPUSCLIP_NO_UPDATE_NOTIFIER.

Claude Code / agents

A Claude Code skill ships with this repo so agents drive the CLI efficiently (the create→watch→download flow, --wait/--exit-status semantics, --json/--jq idioms). It loads automatically inside this checkout. To get it in your own projects:

/plugin marketplace add tdeschamps/opusclip-cli
/plugin install opusclip-cli@opusclip

Exit codes

Code	Meaning	Code	Meaning
`0`	success	`5`	not found (404)
`1`	generic error	`6`	rate limited (429)
`2`	usage / bad flags	`7`	validation (422)
`3`	auth required (401)	`8`	upstream / server / STALLED
`4`	forbidden (403, incl. monthly cap)	`124`	operation timed out

Known gaps & roadmap

v0.1 deliberately ships the core clip workflow. The following are not in v0.1 (documented here so there are no surprises):

No clip list (list-all-projects) — the public API exposes no project-list endpoint. Track the projectIds you create. (v0.2 if an endpoint appears.)
No local file upload — clip create takes a --url only; the upload endpoint isn't in the public spec. (v0.2.)
Virality/judge scores are best-effort — surfaced only when the live API returns them (they're absent from the public spec).
Webhook payloads are opaque — --webhook registers the URL; the delivered payload contract isn't modeled.
Out of scope (v0.1): collections, brand-template management, social posting, censor jobs, AI thumbnails, transcripts.

Development

Built test-first in Go behind interface seams (see ARCHITECTURE.md and CONTRIBUTING.md).

make test       # go test -race ./...
make cover      # coverage profile + total (fails under the 90% gate)
make lint       # golangci-lint
make fmt        # gofumpt + goimports
make build      # ./bin/opusclip

The CI gate runs gofumpt, golangci-lint, go vet, govulncheck, the full race-enabled test suite (unit + testscript e2e), and a cross-compile matrix.

License

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
opusclip command Command opusclip is the entrypoint: it builds the root command, executes it, and maps errors to process exit codes (product spec §9).	Command opusclip is the entrypoint: it builds the root command, executes it, and maps errors to process exit codes (product spec §9).
internal
api Package api is the OpusClip REST adapter: typed models and a thin Client over the documented v0.1 endpoints (clip projects + exportable clips), plus a Raw escape hatch.	Package api is the OpusClip REST adapter: typed models and a thin Client over the documented v0.1 endpoints (clip projects + exportable clips), plus a Raw escape hatch.
auth Package auth owns credential modeling and storage.	Package auth owns credential modeling and storage.
cmd/api Package api implements `opusclip api` — the raw authenticated request escape hatch (like `gh api` / `stripe get`).	Package api implements `opusclip api` — the raw authenticated request escape hatch (like `gh api` / `stripe get`).
cmd/auth Package auth implements the `opusclip auth` command group: login (API key), logout, status, switch, and token.	Package auth implements the `opusclip auth` command group: login (API key), logout, status, switch, and token.
cmd/clip Package clip implements `opusclip clip`: create, get, and watch clip projects.	Package clip implements `opusclip clip`: create, get, and watch clip projects.
cmd/clips Package clips implements `opusclip clips`: list and download a project's generated clips.	Package clips implements `opusclip clips`: list and download a project's generated clips.
cmd/completion Package completion implements `opusclip completion` for bash/zsh/fish/powershell.	Package completion implements `opusclip completion` for bash/zsh/fish/powershell.
cmd/config Package config implements `opusclip config`: get, set, list, edit.	Package config implements `opusclip config`: get, set, list, edit.
cmd/docs Package docs implements `opusclip docs` — open the documentation in a browser.	Package docs implements `opusclip docs` — open the documentation in a browser.
cmd/doctor Package doctor implements `opusclip doctor` — connectivity and credential diagnostics (mirrors `sentry-cli info` / `gh status`).	Package doctor implements `opusclip doctor` — connectivity and credential diagnostics (mirrors `sentry-cli info` / `gh status`).
cmd/info Package info implements `opusclip info` — a friendly banner showing the CLI version, the active configuration, and auth status.	Package info implements `opusclip info` — a friendly banner showing the CLI version, the active configuration, and auth status.
cmd/profiles Package profiles implements `opusclip profiles`: list, use.	Package profiles implements `opusclip profiles`: list, use.
cmd/root Package root assembles the top-level `opusclip` command: it registers global flags, wires the command tree, and configures TTY/color behavior before any subcommand runs.	Package root assembles the top-level `opusclip` command: it registers global flags, wires the command tree, and configures TTY/color behavior before any subcommand runs.
cmd/update Package update implements `opusclip update` — self-update.	Package update implements `opusclip update` — self-update.
cmd/version Package version exposes build metadata injected via -ldflags at release time and the `opusclip version` / `opusclip --version` output.	Package version exposes build metadata injected via -ldflags at release time and the `opusclip version` / `opusclip --version` output.
cmdutil Package cmdutil holds the glue between Cobra commands and the rest of the system: the Factory (dependency injection), global flag state, exit-code mapping, and small command helpers.	Package cmdutil holds the glue between Cobra commands and the rest of the system: the Factory (dependency injection), global flag state, exit-code mapping, and small command helpers.
config Package config handles the layered configuration model described in the product spec: a TOML file holding one or more named profiles, with runtime resolution following the precedence flag → env → profile → built-in default.	Package config handles the layered configuration model described in the product spec: a TOML file holding one or more named profiles, with runtime resolution following the precedence flag → env → profile → built-in default.
help Package help renders the branded landing screen shown for a bare `opusclip` invocation and inside `opusclip info`: a framed ASCII wordmark with a tagline and version, followed by a grouped command listing.	Package help renders the branded landing screen shown for a bare `opusclip` invocation and inside `opusclip info`: a framed ASCII wordmark with a tagline and version, followed by a grouped command listing.
httpclient Package httpclient builds the *http.Client used for all REST traffic.	Package httpclient builds the *http.Client used for all REST traffic.
iostreams Package iostreams provides testable stdin/stdout/stderr handling with TTY and color detection.	Package iostreams provides testable stdin/stdout/stderr handling with TTY and color detection.
output Package output renders command results in the format the context calls for: aligned tables for a TTY, machine-readable JSON/CSV/TSV/YAML when piped.	Package output renders command results in the format the context calls for: aligned tables for a TTY, machine-readable JSON/CSV/TSV/YAML when piped.
text Package text holds small, pure string/time helpers that the rest of the CLI depends on.	Package text holds small, pure string/time helpers that the rest of the CLI depends on.
updatecheck Package updatecheck implements a non-blocking "new version available" notice.	Package updatecheck implements a non-blocking "new version available" notice.