Vincent — User Guide

AI video generation in your terminal.

This guide takes you from a fresh machine to your first finished video: installing Vincent and the tools it needs, talking to the agent, the two video modes, saving and resuming work, and the full command-line surface.

01What is Vincent

Vincent is an interactive AI agent that lives in your terminal and makes videos for you. You describe what you want in plain language; Vincent handles concept writing, image generation, animation, narration, and final video assembly. No video-editing skills required.

It makes two kinds of video:

• Product videos — turn a single product photo into a polished marketing video.
• Story videos — turn a prose idea (or a storyboard you provide) into a narrated, multi-scene video.

Vincent is built on Google Gemini (language model + image generation) and Veo 3 / Veo 3 Lite (video generation). It is a real-time, conversational agent — not a fire-and-forget batch tool — though it also offers a non-interactive vincent make command for scripting (see §11).

02Requirements & install

Vincent runs on macOS and Linux. (Windows is not supported yet.) It needs Node.js 22 or newer (an LTS release; Node 24 is recommended). The easiest way to manage Node versions is nvm:

nvm install 24 && nvm use 24

Then install Vincent globally from npm and confirm it runs:

npm install -g @magyk/vincent
vincent --version

You'll also need ffmpeg (and, for inline video playback, mpv) — Vincent can check for and help install these; see §4.

03Get a Gemini API key

The fastest way to start is a single Google Gemini API key — it covers everything: the language model, image generation, and Veo video generation. (Prefer not to use the cloud? You can run the models on your own hardware instead — see §14, Local inference.) Google AI Studio is the fastest place to get a key:

1. Go to aistudio.google.com and sign in with your Google account.
2. Click Get API key (or API keys) in the sidebar.
3. Click Create API key — in a new or existing Google Cloud project.
4. Copy the key somewhere safe. You'll paste it into Vincent on first run.

04System tools (ffmpeg, mpv, ghostty)

Vincent assembles video on your machine, so it depends on a couple of external tools:

• ffmpeg / ffprobe — required Used to render and assemble every video. Vincent cannot produce output without them. On macOS the ffmpeg build must include libass for burned-in subtitles — see the note below.
• mpv — optional Enables inline video playback (/play) inside the terminal.
• Ghostty or Kitty — optional A graphics-capable terminal, also needed for inline playback. (Vincent runs in any terminal; you just won't get inline video without one of these + mpv.)

Check what you have

vincent doctor

doctor probes your OS for ffmpeg, ffprobe, mpv, and ghostty and prints a status report with per-OS install hints (✓ present, ⚠ outdated/unknown, ✗ missing). It exits non-zero if a required tool is missing. For machine-readable output:

vincent doctor --json

Install the required tools

On macOS and Linux, Vincent can install the required ffmpeg/ffprobe for you, with your consent:

vincent setup            # install missing tools (asks first)
vincent setup --dry-run  # show the plan, change nothing

Useful flags:

Flag	What it does
--dry-run	Print exactly what would be installed without doing anything.
--pinned	macOS only — install SHA256-pinned binaries directly (bypasses Homebrew).
--with-ghostty	Include Ghostty in the install plan (macOS).

On macOS you can also create a clickable launcher:

vincent setup shortcuts --name "Vincent"

Manual install (if you prefer your own package manager):

Platform	Command
macOS	vincent setup (ffmpeg/ffprobe — verified build with libass) · brew install mpv · brew install --cask ghostty Avoid brew install ffmpeg for captions — Homebrew's build lacks libass.
Debian / Ubuntu	sudo apt install ffmpeg mpv
Fedora	sudo dnf install ffmpeg mpv
Arch	sudo pacman -S ffmpeg mpv ghostty
openSUSE	sudo zypper install ffmpeg mpv

Ghostty is available from ghostty.org/download; mpv from mpv.io.

05First run & how to operate Vincent

Launch the interactive app:

vincent                      # start fresh
vincent product.jpg          # start with an image already loaded
vincent --image product.jpg  # same, explicit flag (handy in scripts)

On first run, Vincent prompts you to paste your Gemini API key. It's saved automatically, so you won't be asked again. On later launches, if you have past sessions, Vincent shows a session picker so you can pick up where you left off or start fresh (see §9).

Talking to Vincent

Vincent is a conversation. You don't memorize commands — you describe what you want, and the agent proposes a plan, asks clarifying questions, and does the work. A few mechanics make the conversation flow:

• Give it an image (product mode) by pasting a URL (https://…/product.jpg), pasting a local path (~/Desktop/product.jpg), or typing @ followed by part of a filename to fuzzy-search files across your current directory, ~/Desktop, and ~/Downloads (macOS also searches ~/Pictures via Spotlight). The first image becomes the product image and triggers analysis.
• Proposals. Before anything expensive, Vincent shows a proposal card (a scene plan, a storyboard, a video plan). Press Enter to accept, type feedback to revise it (e.g. "make it more cinematic"), or press Esc to dismiss. (You can also type a/accept or d/dismiss.)
• Progress. Long-running steps show a labelled spinner ("Analyzing image", "Rendering video", "Storyboarding").
• View results. When a video is ready, use /play to watch it inline (needs mpv + a graphics terminal) or /open to open it in your system viewer. /checkplay diagnoses inline-playback prerequisites.

Type /help at any time for the command list, and /status to see the current session's ID, model, and how many images/videos you've made.

06Product mode

Product mode turns a single product photo into a marketing video. It's the default mode, and Vincent auto-enters it when your first input is an image URL or file path.

The typical flow is a guided, proposal-driven sequence:

1. Analyze the product — Vincent studies your image (type, colors, materials, styling) to ground everything downstream.
2. Propose scenes — it designs a set of scenes (hero shot, context, detail, lifestyle) and shows them for your approval.
3. Generate scene images — after you approve, it generates each scene image. You can ask for edits to any of them.
4. Plan animation — it works out motion (camera pans, product rotations).
5. Propose the video — aspect ratio, music, pacing, transitions — shown as a final plan to approve.
6. Render — Vincent assembles everything into an mp4 and tells you when it's ready.

At each proposal you stay in control: accept, give feedback to revise, or dismiss and try a different direction. Use /memories to see creative preferences and guidance Vincent has remembered for you.

07Story mode

Story mode turns an idea into a narrated, multi-scene video. Enter it by typing /mode story (Vincent also switches automatically if you paste a storyboard JSON). To start, just describe what you want — a sentence is enough — and optionally mention length, tone, audience, or language.

Storyboard first, then render

Story mode works in two phases, on purpose:

• Storyboarding (cheap, iterative). Vincent drafts a storyboard — scene titles, narration, and image prompts — and shows it for review. This is fast and free to revise: tweak narration, swap an image prompt, add or remove a scene, change the voice, aspect ratio, language, or subtitles. Iterate until it's right.
• Rendering (committed). Only when you approve does Vincent render the approved storyboard into a finished video.

Enhance without re-rendering from scratch

Once a video exists, you can refine it through conversation and Vincent re-composes just what changed, rather than regenerating everything:

• Add, change, or remove background music (a built-in mood, a URL, or a track from your library — see §12).
• Animate still scenes to add motion.
• Rewrite narration and re-record the audio.
• Regenerate a single scene's image with a new prompt.
• Apply a reference image to keep a character or setting consistent across scenes — upload a photo and ask Vincent to use it as the reference; it anchors every scene to that image and re-renders with an image-editing model (set via the imageEdit slot — see §12).
• Add or reposition a logo overlay.
• Restyle subtitles or change scene transitions.

08Switching modes & shared memory

Product and Story are two modes of the same session. Switch any time:

/mode product
/mode story

Vincent auto-routes based on your first input — an image goes to Product mode, a pasted storyboard JSON goes to Story mode — and if your goal clearly fits the other mode, the agent may offer to switch for you.

The two modes share a project brief: durable decisions and creative preferences you establish in one mode carry across to the other and survive resume, so you don't repeat yourself. Each mode keeps its own conversation branch, so switching back and forth doesn't tangle the two histories.

09Sessions & resume

Every session is saved automatically — your conversation, generated images and videos, and the decisions Vincent remembered. There's nothing to save manually.

When you relaunch vincent and prior work exists, Vincent presents a session picker: choose a past session to continue editing, or start a new one. Resuming restores your completed videos and the project brief so you can keep going.

• /rename <name> — label the current session so it's easy to find in the picker (e.g. /rename Nike Air Max).
• /new — start a fresh session with a clean work directory.

Videos rendered by the non-interactive vincent make command also save a normal session, so you can open them in the interactive app from the picker and keep editing.

10Slash command reference

Type these inside the interactive app.

General

Command	Description
/help	Show the command list and tips.
/status	Show session state — ID, step, model, image/video counts, work dir.
/settings	Configure API keys and models.
/about	Show version and open-source notices.
/new	Start a fresh session (clears chat, new work directory).
/open [ref]	Open an artifact in your system viewer. Refs: image, image1, video, video1, original, dir.
/play [ref]	Play a video inline in the terminal. Refs: video, video1, latest.
/checkplay	Check inline-playback prerequisites (mpv + graphics terminal).
/thinking on|off	Toggle display of the agent's thinking.
/quit	Exit the app.

Session & modes

Command	Description
/mode product|story	Switch the active workflow mode.
/rename <name>	Rename the current session (shown in the picker).
/diagnostics	Package the current session + an environment report into a .zip (in the current directory) to attach to a bug report. No API keys; your home path is rewritten to <HOME>.
/update	Update Vincent to the latest published version.
/memories	product Show saved guidance and creative preferences.

11Non-interactive — vincent make

For scripting and one-shot renders, vincent make renders a video from the command line with no TUI. It saves a normal, resumable session, so you can open it later in the interactive app and keep editing.

# From a prose idea (one-shot: generates a storyboard, then renders):
vincent make story "A 30-second story about a lighthouse keeper who finds a message in a bottle" --length 4

# From a storyboard JSON you control (deterministic, no LLM planning):
vincent make storyboard ./storyboard.json --out ./out.mp4

# From a product image + a brief (one hero shot → video):
vincent make product ./product.jpg "on a model in a sunlit loft" --out ./out.mp4

Common flags:

Flag	Description
--json	Emit one JSON result object on stdout; all progress goes to stderr (scriptable).
--out <path|dir>	Copy the final mp4 to a path or directory. Fails if it exists unless --force.
--force	Overwrite an existing --out target.
--no-session	Render only; don't save a resumable session.
--session-id <id> / --session-name <name>	Pin the session id / its display name in the picker.
--storage <dir>	Override the artifact output directory.

make story also accepts the pipeline flags (--length, --ar, --voice, --language, --animate, --music, …) described in §12.

With --json, a successful run prints exactly one object:

{
  "ok": true,
  "videoPath": "/path/to/video.mp4",
  "sessionId": "…",
  "workDir": "…",
  "renderDir": "renders/v…",
  "version": 1
}

On failure it prints { "ok": false, "error": "…" } and exits non-zero. This makes it easy to script:

vincent make storyboard ./sb.json --json --no-session | jq -r '.videoPath'

12CLI & options reference

The canonical, always-current reference is vincent --help. The essentials:

Interactive launch options

Option	Description
--image <url|path>	Product image (also accepted as a positional argument).
--video-model <id>	veo3 or veo3-lite (default: veo3-lite).
--storage <path>	Override the artifact output directory.
--user-id <id> / --username <name>	Identify the session (defaults: tui-user / TUI).
--self-test	Run built-in diagnostics and exit (no key or terminal needed).
-v, --version	Print the version and exit.
-h, --help	Show full help and exit.

Subcommands

Command	Description
vincent make story|storyboard …	Non-interactive render (§11).
vincent models list|current|doctor [--json]	Inspect the curated models, the resolved per-slot choice, and which providers are configured (read-only).
vincent models capabilities <id> | --slot <slot>	Show a model's capabilities (aspect ratios, durations, prompt style).
vincent models set <slot> <model-id>	Set the model for a slot (llm|imageGenerate|imageEdit|video|tts). Image is split by operation: imageGenerate is text-to-image (Story scene art); imageEdit edits a source or reference image (Product photo edits and Story reference anchors). The llm slot is the planner/pipeline model used by make — not the interactive Vincent agent. Warns (but still saves) if the provider isn't configured.
vincent models preset [<name>]	Apply a preset (starter-google, google-pro, open-providers); no name lists them.
vincent doctor [--json]	Check ffmpeg/mpv/ghostty and show install guidance.
vincent diagnostics [<id>] [--latest] [--out <dir>]	Zip a session — transcript, logs, and an environment report — for a bug report (the headless form of /diagnostics). Defaults to the latest session, written to the current directory.
vincent setup [--dry-run] [--pinned] [--with-ghostty]	Install missing required tools (ffmpeg/ffprobe) with consent. macOS & Linux only.
vincent setup provider <id>	Store an API key for a provider (google, anthropic, replicate, fal, elevenlabs, openai) — the non-interactive equivalent of the in-app key dialog.
vincent local connect <host>	Point all local providers at one host (sets the ComfyUI / local-LLM / Kokoro / Whisper endpoints from a single hostname or IP). For self-hosted inference — see §14.
vincent local set <provider> <url> / local clear <provider> / local show	Set/clear one local endpoint, or list configured endpoints and the local models each offers.
vincent setup shortcuts [--name] [--args]	Create a clickable launcher (macOS).
vincent music install <file> [--title] [--mood]	Add a local audio file to your music library.
vincent music list / music remove <id>	List bundled + your tracks / remove one of yours.

Story / pipeline flags (most useful)

These shape a make story render (and mirror the choices the Story agent offers interactively):

Flag	Description
--length <n>	Number of scenes.
--ar <portrait|landscape|square>	Aspect ratio (also accepts 9:16, 16:9, 1:1).
--voice <name>	Narrator voice.
--language <lang>	Narration language (e.g. english, hindi, spanish).
--animate	Animate each scene (adds render time).
--music <mood|url|id>	Background music: a built-in mood, a URL, or a library track id.
--genre, --target, --pov, --visual	Creative direction: genre, target audience, narrator POV, visual style.
--logo <url>	Overlay a logo image.
--subPosition, --subStyle, --subSize …	Subtitle placement and styling.

Many more pipeline flags exist (transitions, borders, progress bars, fine subtitle control, and so on). Run vincent --help for the complete, authoritative list.

13Settings, storage & environment

Settings & API keys

API keys and model preferences are stored in a JSON settings file:

OS	Settings file
Linux	~/.local/share/magyk/settings.json
macOS	~/Library/Application Support/magyk/settings.json

Use /settings inside the app to configure keys and the video model, or edit the file directly. Environment variables take priority over the settings file.

Vincent ships Google Gemini + Veo as the default ("starter") models — one GEMINI_API_KEY gets you everything. The registry also lists alternative cloud providers (Replicate, fal, ElevenLabs, OpenAI) for advanced setups, plus local / self-hosted models you run on your own hardware (configured by endpoint URL rather than a key — see §14). Run vincent models list to see every curated model and which providers you have configured, and vincent models doctor to check per-slot readiness. To change a choice, use vincent models set <slot> <model-id> or apply a preset with vincent models preset <name> (starter-google restores the all-Google default). The llm slot controls non-interactive planning/generation (e.g. make story planning), not the interactive Vincent agent. vincent models never prints your API keys.

Story honors your imageGenerate, imageEdit, video, TTS, and llm selections at render time — including the llm slot, which now drives Story planning (script, image prompts, and animation prompts). Scenes drawn from scratch use your imageGenerate model; scenes anchored to a reference image (see §7) use your imageEdit model. If a selected model can't be honored — an edit-only model picked for imageGenerate, or a reference scene whose imageEdit provider isn't configured — Vincent fails with a clear message rather than silently substituting another model. The llm slot is the planner/pipeline model — it does not change the interactive Vincent chat agent.

Environment variables

Variable	Purpose
GEMINI_API_KEY	Your Gemini key. Overrides the saved key if set.
MAGYK_ENV_FILE	Path to an explicit dotenv file to load.
MAGYK_VID_STORAGE	Base directory for artifact output (the --storage flag overrides this).
COMFYUI_URL	ComfyUI endpoint for local image + video (see §14). Normally set via vincent local, not by hand.
LOCAL_LLM_URL	OpenAI-compatible local LLM endpoint (e.g. Ollama) for local planning.
LOCAL_TTS_URL	Kokoro TTS endpoint for local narration.
LOCAL_WHISPER_URL	Optional whisper endpoint for accurate word-level subtitle timing.

The four *_URL endpoints above are normally written by vincent local connect / the /settings Local endpoints rows; set them directly only to override per-shell. Render-tuning knobs (MAGYK_LOCAL_IMAGE_RESOLUTION, MAGYK_LOCAL_VIDEO_SHORT_EDGE, …) are documented in §14.

Where files live

By default (no --storage override), generated artifacts and session transcripts are stored under the Magyk data directory:

OS	Artifacts (genartifacts)
Linux	~/.local/share/magyk/genartifacts/
macOS	~/Library/Application Support/magyk/genartifacts/

Each session gets its own work directory containing the original image, generated images, the rendered video(s), and a session log. Resumable session transcripts live alongside, under …/magyk/transcripts/.

14Local / self-hosted inference advanced

By default Vincent calls cloud models (Gemini/Veo, and optionally Replicate/fal/ElevenLabs/OpenAI). You can instead run the generative models on your own machine — an Apple-Silicon Mac is the reference setup — for privacy (nothing leaves your network) and no per-use cost. The trade-off: local generation is much slower than cloud (a 3-scene 1080p story ≈ 30 min on Apple Silicon), and you maintain the servers. You can also mix: local for some slots, cloud for others.

Standing up the box itself (installing and running Ollama, ComfyUI, Kokoro, and optionally whisper, reachable over your network) is a separate one-time setup outside this guide. This section assumes those servers are already running and reachable.

The local providers

Local providers are configured by an endpoint URL, not an API key:

Provider	Serves	Default port	Reference server
local-llm	LLM (planning)	11434	any OpenAI-compatible server (Ollama is the reference)
comfyui	image + video	8188	ComfyUI
kokoro	TTS (narration)	8880	Kokoro (kokoro-fastapi)
whisper (optional)	word-level subtitle timing	8081	whisper.cpp whisper-server

1 — Point Vincent at your box

If all the servers run on one host, connect them in a single command:

vincent local connect <host>   # e.g. vincent local connect 100.74.1.94 (a Tailscale IP)
vincent local show             # list endpoints + the local models each one offers

Or set one at a time — vincent local set <provider> <url> / vincent local clear <provider>. You can also set endpoints inside the app: /settings has a Local endpoints section (ComfyUI / Local LLM / Kokoro / Whisper) — press Enter on a row to type the URL.

2 — Select the local models

Once an endpoint is set, that provider's models become selectable. Pick them per slot — on the CLI or in /settings (cycle a row with Enter):

vincent models set llm           local-qwen3
vincent models set imageGenerate local-flux-schnell
vincent models set imageEdit     local-flux-kontext
vincent models set video         local-ltx
vincent models set tts           local-kokoro

Slot	Model id	What it is
llm	local-qwen3	Qwen3 30B via Ollama (ollama pull qwen3:30b) — general-purpose planner; good creative range for scene writing and storyboarding
imageGenerate	local-flux-schnell	Flux Schnell text-to-image (Story); draft quality, fast
imageEdit	local-flux-kontext	Flux Kontext source-image editing (Product / reference scenes)
video	local-ltx	LTX-Video image-to-video
tts	local-kokoro	Kokoro narration

Local providers are never auto-selected — the cloud defaults stay until you pick a local model. If you pick a local model whose endpoint isn't set, Vincent fails with a clear message (it tells you to run vincent local connect) rather than silently falling back.

Subtitles & the optional whisper server

Kokoro returns audio only, so by default Vincent estimates word timings — fine for simple subtitles. For accurate karaoke / animated subtitle styles, run the optional whisper server (forced alignment): set its endpoint and Vincent uses real per-word timing automatically, falling back to estimation if it's unavailable.

Performance & tuning

Local generation on Apple Silicon (MPS) is the slow part — flux images render in minutes and LTX video clips dominate. The shipped defaults target publishable quality (1080p output, images at 720p, video upscaled from 576). To trade quality for speed (e.g. quick drafts), set these env vars:

Variable	Default	Effect
MAGYK_LOCAL_IMAGE_RESOLUTION	720p	Flux generation resolution (e.g. 480p for faster/softer)
MAGYK_LOCAL_VIDEO_SHORT_EDGE	576	LTX clip short edge in px (e.g. 320 faster, 768 sharper)
MAGYK_LOCAL_VIDEO_SECONDS	6	Clip length in seconds
MAGYK_LOCAL_RENDER_TIMEOUT_MS	image 20m / video 30m	Per-render timeout (raise for very large renders)

Vincent submits one job at a time to a local box (the GPU is shared), so renders are predictable but serial — concurrency wouldn't speed up a single-GPU machine anyway.

15Troubleshooting & tips

• Something's not working? Run vincent doctor to check your tools, and vincent --self-test to verify the install (work dir, fonts, prompts, settings) without needing a key.
• Found a bug, or have a feature request? Report it at github.com/magyk-ai/vincent/issues. If a specific session misbehaved, run /diagnostics in the app (or vincent diagnostics --latest after quitting) to bundle that session — transcript, logs, and an environment report — into one .zip you can attach. It carries no API keys and rewrites your home path to <HOME>. Otherwise vincent --self-test output (Node version, terminal type, tool availability, settings state) is a good start.
• Inline video won't play? Run /checkplay. Inline playback needs mpv plus a graphics-capable terminal (Ghostty or Kitty). Otherwise use /open to view in your system player.
• "API key" errors. Confirm a key is set — either via /settings, the settings file, or the GEMINI_API_KEY environment variable (which wins). If renders fail mid-way, check your AI Studio quota/billing — Veo is the most quota-hungry step.
• Update Vincent. Use /update inside the app, or reinstall: npm install -g @magyk/vincent@latest. Restart afterward to use the new version.
• Check your version. vincent --version.