agent-video CLI reference

agent-video is the standalone Go CLI for Agent Video — a self-hosted video-sharing product. It logs you in over OIDC, uploads local video files with a chunked resumable protocol, manages a video's metadata and chapters, mints machine bearer tokens, wires Claude Code's ./.mcp.json to a stdio MCP server, and prints usage.

The CLI source lives in src/agent-video/ (a separate Go module from the Next.js server). See the releases page.

Synopsis

agent-video <command> [options]

login        Log in to an Agent Video server (OIDC loopback browser flow)
upload       Chunked resumable upload                    [FILE]
video        List your videos                            [aliases: videos, list, ls]
show         Show one video's metadata                    [ID]
edit         Update title/description/privacy/password    [ID]
chapters     Set or add chapter markers                   [ID]  [alias: chapter]
rm           Delete a video                                [ID]  [aliases: delete, remove]
token        Manage machine bearer tokens (mint/list/revoke) [alias: tokens]
mcp          Run the stdio MCP server (upload/list/show tools)
install      Wire ./.mcp.json to run `agent-video mcp`     [aspire]
version      Print the CLI version                        [--version, -v]
help         Show usage                                    [-h, --help]

Global environment variables

OIDC login requests scopes openid profile email offline_access.

Config/credential dir. The default is ~/.agent-video. When USE_ASPIRE is truthy (or install aspire is used), the CLI uses ~/.agent-video-aspire instead so a local login never clobbers your production credentials. Override the location with AGENT_VIDEO_HOME.

login

Logs in to an Agent Video server using an OIDC loopback (browser) flow, then saves the refresh token, your sub, and your display name to the credential store. After saving, it sanity-checks the token with a videos-list call (warns but doesn't fail if the server is unreachable).

Stale or dead refresh tokens auto re-login inline when running on a TTY; non-interactively the CLI prints copy-paste re-login instructions.

upload FILE

Uploads a local video file using a chunked (8 MiB), resumable protocol. The file is streamed — never buffered whole in memory — via io.SectionReader per chunk. Each chunk retries up to 5 times with exponential backoff (500ms → 30s cap). A TTY shows a live progress line (percent, bytes, throughput, ETA); a non-TTY (CI/log) gets one plain line per 10% crossed.

Resumability. The CLI keys local resume state off a hash of (absolute path, size, mtime). If you re-run the exact same command against the same unmodified file after an interruption, it asks the server how many chunks it actually received (GetUploadStatus) and continues from there — never re-sending data the server already has. If the server has forgotten the session (past its retention window), the CLI safely abandons it and starts a fresh upload.

agent-video upload session.mp4 --title "Sprint demo" --tag demo --wait

video (aliases: videos, list, ls)

Lists your videos, newest first: id, status, privacy, title.

show ID

Prints one video's full metadata: title, description, privacy, status, duration, tags, chapters, view count, share URL, created-at.

edit ID

Updates a video's title, description, privacy, and/or password. Only the flags you actually pass are sent — an unset --title never clobbers the stored title.

At least one of --title/--description/--privacy/--password is required; passing none is a usage error.

agent-video edit abc123 --privacy password --password "letmein"

chapters ID (alias: chapter)

Sets or appends chapter markers on a video. Pass exactly one of --set or --add.

agent-video chapters abc123 --add "1:30=Intro"
agent-video chapters abc123 --set chapters.json

chapters.json:

[
  { "timestamp": 0, "title": "Intro" },
  { "timestamp": 90, "title": "Deep dive" }
]

rm ID (aliases: delete, remove)

Deletes a video.

Without --force, the CLI prompts Delete "<title>" (<id>)? on a TTY; a non-interactive run (no TTY on stdin) refuses outright rather than silently deleting or silently proceeding.

agent-video rm abc123 --force

token (alias: tokens)

Manages machine bearer tokens — issued for CI runners or agents that can't run an interactive browser login. Minting/listing/revoking a token always requires a real OIDC login (ownerAccess); a machine token itself can never be used to mint more machine tokens, so a leaked token has no way to self-escalate.

token mint (alias: create)

Mints a token and prints it once.

agent-video token mint --label "CI runner"

token list (alias: ls)

Lists your machine tokens: id, label, and relative last-used time.

token revoke ID (aliases: rm, delete)

Revokes a token by id.

agent-video token revoke <ID>

mcp

Runs the stdio MCP server exposing upload, list, and show as tools, so a coding agent can publish a video with no shell access. Auth is resolved exactly like every other command: AGENT_VIDEO_TOKEN wins when set, otherwise the stored OIDC login is used (auto-refreshed) — no secret needs to live in the MCP config itself. Progress output is suppressed (silent reporter) so no terminal control sequences leak into the stdio JSON-RPC stream.

See the MCP tools reference for the full tool catalog and argument shapes.

install [aspire]

Wires ./.mcp.json (Claude Code's project-scoped MCP config) to run agent-video mcp, preserving any other servers already in the file. No secret is written to the file — auth comes from your stored login (or AGENT_VIDEO_TOKEN in the environment) — so it's safe to commit.

agent-video install            # wires the hosted/production server (default)

install aspire [resource]

Wires ./.mcp.json to a local Aspire resource instead of production. The resource defaults to video. The CLI runs aspire describe <resource> --format Json, prefers the resource's PUBLIC_BASE_URL (falling back to the loopback URL), pulls OIDC_ISSUER if set, and points AGENT_VIDEO_HOME at ~/.agent-video-aspire so a local login doesn't clobber prod credentials.

agent-video install aspire video

version / help

agent-video version      # also --version, -v  → prints "agent-video <version>"
agent-video help         # also -h, --help

.mcp.json secrets

./.mcp.json is project-scoped Claude Code config. Every path that writes it (install, install aspire) writes no secret — auth is always your stored login (or AGENT_VIDEO_TOKEN from the environment at run time), so the file is safe to commit.

See also

• Quickstart — install, sign in, upload your first video.
• MCP tools reference — every tool and argument shape.