v-flow

Move footage and photos between camera cards, long-term storage, and editing drives without ever losing track of the safe copy.

Wait, what does it do?

v-flow is a CLI for people who shoot a lot of video and photos. It copies your camera card into a protected archive and proves the copy with checksums. It puts temporary copies on your editing SSD, saves finished videos and DaVinci Resolve backups, and deletes an editing copy only after verifying the archived original. Nothing is ever moved or deleted as a side effect of anything else.

You can drive it from the terminal, or just talk to Claude Code, Codex, or Cursor. The bundled skill teaches your agent the whole workflow.

Install

curl -fsSL https://raw.githubusercontent.com/kaungzinye/v-flow/main/install_vflow.sh | bash

That installs the v-flow command plus the agent skill. Claude Code and Cowork users can grab the plugin instead, and the skill installs the CLI from PyPI on first use:

/plugin marketplace add kaungzinye/v-flow
/plugin install v-flow@v-flow

Then point it at your drives:

v-flow make-config

Then check the whole environment in one command, which tells you in plain words what works and what to fix:

v-flow doctor

Use it

Ingest a card. Footage lands in a Shoot, photos in a Collection, one command:

v-flow ingest --source "/Volumes/SDCARD" --auto

Put a Shoot on your editing drive, and clean it up when you're done (cleanup verifies checksums and your Resolve project first):

v-flow checkout --shoot "2026-08-02_Ingest" --working-location work_ssd
v-flow cleanup  --shoot "2026-08-02_Ingest" --working-location work_ssd --project "Summer Film" --confirm

Or skip the flags entirely and ask your agent:

Ingest this card, then put the footage on my SSD.

Every state-changing command supports a dry run, names the safety gate that failed, and leaves your card and archive intact on any error.

Every decision v-flow needs has a flag that carries it, such as --confirm for a deletion or --merge-into for a date overlap. Reach one without the flag and without a terminal to ask, and the command stops and names the flag rather than guessing. Long copies print plain progress lines, and an interrupted run resumes when you re-run the same command.

Notes

This is a personal tool that grew documentation. It works on macOS, it's tested, and it guards your media obsessively. Still, expect sharp edges in places one person's workflow never reached.

Docs

• The agent skill: the workflow reference, branch by branch
• Domain language: what Shoot, Collection, Archive, and friends mean precisely
• Every command: v-flow --help

Contributing

Issues and PRs welcome. Read CONTEXT.md first. The vocabulary is load-bearing.