Frame.io Agent

by VAXA Studio

Turn your coding agent into an assistant editor who actually knows Frame.io.

Ask your agent, from anywhere:

• "Dig through today's clips and cut me a reel of only the shots that don't suck." → frames pull hands your agent a frame from every clip; it judges them and ships the keepers as a review link.
• "Read every note the client left on v7 and tell me what they actually want." → comments --json returns every note with timecodes; your agent does the diplomacy.
• "Contact sheet of the shoot — minus every take with a C-stand in the background." → your agent looks at the frames, spots the C-stands, rebuilds the sheet without them.

The CLI has no LLM inside it — it gives whatever agent you already run (Claude Code, Cursor, Codex, Gemini CLI, any OpenRouter harness) clean JSON, real pixels, and confirmation-gated write commands. Read-only by default; it can't delete, rename, move, or change permissions. Ever.

<!-- TODO: 5-second terminal GIF of the success moment (frames pull → agent judges → filtered contact sheet). Record after next live run. -->

Unofficial community tool. Not affiliated with, endorsed by, or supported by Adobe or Frame.io. "Frame.io" is a trademark of Adobe.

---

Prerequisites

• A Frame.io V4 account (the next.frame.io platform — legacy v3 fio-u-* tokens won't work).
• An Adobe ID that can open the Adobe Developer Console and add the Frame.io API (free; one-time ~5-minute OAuth app setup — the wizard walks you through it).
• Python 3.10+ and git.
• Optional: a multimodal agent for the vision workflows; pip install "frameio-agent[images]" for contact sheets; [youtube] for YouTube/X ingestion.

Quick start (with an agent)

git clone https://github.com/sheldondirector/frameio-agent
cd frameio-agent

Then paste this to your coding agent:

Connect this repo to my Frame.io account.
1. Read AGENTS.md — it has the rules and the agent-driven login flow.
2. Install deps: python scripts/setup.py
3. Set up .env from .env.example (ask me for my Adobe OAuth Client ID and Secret).
4. Authenticate with the two-step flow: run `frameio-agent auth start --json`,
   show me the sign-in URL, and when I paste the redirect URL back, run
   `frameio-agent auth complete "<that url>"`.
5. Run `frameio-agent verify`.
6. Then: find my latest cut and summarize its review comments with timecodes.
Never print secrets. Prefer --json when parsing.
Every write command shows a confirmation summary — ask me before using --yes.

Quick start (manual, human at the terminal)

python scripts/setup.py                          # install deps
python -m frameio_agent.cli auth login            # guided OAuth wizard (interactive)
python -m frameio_agent.cli verify
python -m frameio_agent.cli projects --json
python -m frameio_agent.cli latest --project <id> --json
python -m frameio_agent.cli comments <file_id> --json

What it does

Read (no confirmation needed):

• auth login — guided Adobe IMS OAuth wizard with clipboard auto-detect (for humans at a terminal). Agents use auth start / auth complete instead — non-interactive, documented in AGENTS.md.
• auth status / verify — confirms the connection without printing tokens.
• projects --json — lists accounts / workspaces / projects.
• latest --project <id> — newest-updated video assets, recency-first.
• search "<query>" — account-wide search. Add --nlp for natural-language matching ("red car driving on highway"), or keep the default lexical engine for exact names.
• comments <file_id> --json — normalized review notes (timecode + timestamp_seconds + author + thread).
• brief --project <id> — one-paragraph project status.

Vision (give your agent eyes):

• frames pull --project <id> --out ./frames — download one preview frame per clip + a manifest.json mapping each image back to its file_id. Read-only; writes only local files. Your multimodal agent then looks at the frames, judges them, and drives the next command — share create with the selects, or contact-sheet --from-manifest --exclude with the rejects. Works with any agent that can read an image.
• contact-sheet --project <id> --out sheet.png — thumbnail grid of a project or folder. Filter with --only/--exclude file_id lists, number tiles with --index, or build offline from a frames pull manifest with --from-manifest.

Write (every one is confirmation-gated):

• share create <file_id> [...] --name "..." — bundle assets into a Frame.io review share. Multi-asset; --reviewers a@x.com,b@y.com sends email invites (max 10); --expires, --password, --no-download. Default visibility is public-link; --restricted requires the secure_sharing feature on paid Frame.io plans (the CLI tells you plainly if yours lacks it).
• refs add <url-or-path> --folder <folder_id> — pull a YouTube/X/TikTok/Vimeo URL via yt-dlp, upload a local file, or point Frame.io at a direct URL it can fetch itself. One command, mode auto-detected.

Read-only by default. Mutations only fire after an explicit y/N confirmation (or --yes when the user has authorized that specific action).

Security

• Read-only by default; every mutation is opt-in and confirmation-gated. Share creation and reference uploads require y/N (or an explicit, user-authorized --yes). No silent writes ever. Comment posting is not shipped; comments is read-only.
• Delete / rename / move / permission-change are NOT in scope. Those endpoints exist in Frame.io V4; the CLI just doesn't call them — and AGENTS.md instructs agents not to add them.
• Secrets stay local. .env and the token cache are git-ignored; the CLI redacts token-like values from all output; share passwords are never echoed.
• Bring your own credentials. Nothing is ever sent to the maintainers.

Which agents work with this?

Any agent that can run local shell commands — the model is entirely your choice:

• Claude Code / Cursor / OpenAI Codex CLI / Gemini CLI — paste the quick-start prompt above and go.
• OpenRouter-backed agents (Aider, OpenHands, Cline, custom harnesses — any model): same thing. For the vision workflows, pick a multimodal model.
• Agent-driven login: agents use the non-interactive auth start --json → auth complete "<redirect-url>" pair; the interactive auth login is for humans at a terminal.

Optional: MCP

If your agent supports MCP, run frameio-agent mcp to expose the core read operations (auth status, projects, latest, comments) as MCP tools. The CLI is the spine and carries the full command surface — MCP is a thin, read-only wrapper.

Troubleshooting

If you see	Do
Missing FRAMEIO_CLIENT_ID	Run frameio-agent auth login (or auth start if an agent is driving)
Frame.io is not authenticated / session expired	Re-run the login flow
no pending login (or it expired)	Run frameio-agent auth start again (15-min TTL)
Could not resolve an account_id	Set FRAMEIO_ACCOUNT_ID in .env (find it via projects --json)
feature(s) not included in plan: secure_sharing	Use the default --public share, or upgrade the Frame.io plan
Warning: collection cap reached	Re-run with a higher --max-files
yt-dlp is not installed	pip install "frameio-agent[youtube]"
Pillow is required	pip install "frameio-agent[images]"

Roadmap

Open issues track what's next: PyPI/pipx packaging, HTTPS-loopback zero-paste auth, multi-frame extraction via ffmpeg. See Issues.

License

MIT. See LICENSE.

Credits

Built by VAXA Studio — we make tools for creative teams using coding agents. Developed with Claude Code (Claude, by Anthropic) as pair programmer — architecture, implementation, tests, and this README were co-authored across human/agent sessions.

Unofficial community tool. Not affiliated with, endorsed by, or supported by Adobe or Frame.io.