Commands

npx vfrey --version prints the installed version. Run every command as npx vfrey ... from your project folder (or any folder inside it). Start a project with npm create vfrey@latest my-channel (beta: @beta). Outside a project, use npx @vfrey/vfrey ... instead of npx vfrey ..., or install it once with npm i -g @vfrey/vfrey and run vfrey ... anywhere. See Projects. Words in capitals, like JOB_ID, are placeholders. npx vfrey --help lists the same commands, and npx vfrey COMMAND --help lists one command’s flags.

Start a project

Command	What it does
`npm create vfrey@latest [DIR]` (or `npx create-vfrey [DIR]`)	Starts a project in a new folder (default `vfrey`), runs `npm install` and `vfrey doctor`, and prints the next step. It never asks a question, so an agent can run it. It refuses a folder that is not empty, unless it is already a project (then it repairs it). Flags: `--name NAME`, `--agent claude\|codex\|grok\|cursor\|gemini\|all` (tailors only the printed next step; every agent’s files are always written), `--engine ENGINE_ID`, `--no-install`, `--from DIR`.
`npx @vfrey/vfrey init` (inside a project: `npx vfrey init`)	Makes the current folder a project: `vfrey.json`, `package.json`, `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, the skill for every agent, `scenes/`, `scripts/`, `videos/`, `.vfrey/`. Run it again to repair: files that exist are kept. `--name NAME`, `--engine ENGINE_ID` (recorded in `vfrey.json` as the project’s engine), `--from DIR`.
`npx vfrey projects`	Lists the projects on this machine with each one’s last video and whether its dashboard is up. `--json` prints it for a machine. `--prune` drops projects whose folder is gone.

--from DIR imports a data folder, such as the machine desk ~/.vfrey: its database, its videos as readable files with transcripts, and its scene copies. The source is not changed. See Projects.

Make a video

Command	What it does
`npx vfrey doctor`	Checks the machine: Node, the data folder, Chrome, the voice, and the skill. Exits non-zero when a check fails. `--json` prints a report and always exits 0. `--rules` prints the checklists.
`npx vfrey tick --now`	Makes one video now: source, generate, render, publish.
`npx vfrey tick --now --about "SUBJECT"`	Makes a video about that subject instead of the default feed.
`npx vfrey tick --now --about "SUBJECT" --script script.json`	Makes a one-off video with a script you wrote. See Your agent.
`npx vfrey tick --script-template`	Prints an example `script.json`.
`npx vfrey worker`	Runs a tick every 60 seconds until you stop it. `--dry-run` skips the real render and upload.
`npx vfrey worker --all-projects`	Each cycle, ticks every project on the machine that has a due, unpaused series. `--once` runs one cycle and exits. Logs to `~/.vfrey/logs/worker.log`. See Background worker.
`npx vfrey render --subject "TEXT"`	Renders one vertical 1080×1920 picture. Uses the project’s engine, else the machine default, unless you pass `--engine ID`. `--composition NAME` (default `KineticType`) and `--output FILE.mp4` are also taken. An empty subject is refused.

script.json is { "title", "hook", "lines", "hashtags" }: a title up to 100 characters, a required hook, 4 to 12 lines of up to 220 characters each, and 1 to 8 hashtags that start with #. The lines must use at least 2 of the subject’s key words, or the script is rejected for subject-binding. More than 8 lines are folded into 8 visual beats, and the voice still reads every line. Without --about, the subject is the script’s subject field, else its title. Without --script, vfrey writes a basic script itself, which is a placeholder unless a model is configured. A run with --about or --script is a one-off video, and a series job in progress does not block it. tick also takes --json for a machine summary (it has project as {name, root} or null, and each job has engage as {status, code} and checks, the quality checks), --dry-run to skip the real render and upload, and --skip-render to skip the render (no real MP4). --series ID runs only that series. --scene DIR renders a scene you wrote. --engine ENGINE_ID picks the render engine for this run. After a run it prints the MP4 path, the transcript path, and the upload result. In a project the MP4 is videos/YYYY-MM-DD TITLE.mp4. Each job ends with a See it: line, a live link to its run page. The tick starts this project’s dashboard in the background when it is not running, so the link works. VFREY_NO_DASHBOARD=1 turns that off (it still uses a dashboard that is already running). If the dashboard cannot start, the line is See it: npx vfrey open RUN_ID instead. When nothing runs, it prints why.

Scenes

Command	What it does
`npx vfrey scene blocks [--category X] [--json]`	Lists the ready-made scene blocks: name, category, size, duration, and a description.
`npx vfrey scene add BLOCK DIR [--force] [--json]`	Copies a block into the scene folder `DIR` and prints the snippet to paste into `#root`. An edited copy is kept unless you pass `--force`.
`npx vfrey scene transitions [--json]`	Lists the 15 shader transitions for `vfrey.transition` in an HTML scene. Remotion scenes do not support them.
`npx vfrey scene init DIR`	Writes a starter scene (`DIR/index.html`) and vfrey’s files in `DIR/vfrey/`. `--engine framey` (default), `hyperframes`, or `remotion` (writes `DIR/index.tsx`).
`npx vfrey render --scene DIR --engine ENGINE_ID --frame SECONDS out.png`	Writes one silent frame of your scene so you can look at it. `--script script.json` sets the text.
`npx vfrey render --scene DIR --engine ENGINE_ID`	Renders the whole scene to an MP4. `--output FILE.mp4` sets where.
`npx vfrey tick --now --about "SUBJECT" --script script.json --scene DIR --engine ENGINE_ID`	Makes the video with your scene instead of the default template.

| npx vfrey scene inspect DIR [--at SECONDS] [--selector CSS \| --text "words"] [--script FILE] [--json] | Before a “change just this” edit: which element, CSS rule, and GSAP tween (with file and line) make the thing you name. Every visible element by default. HTML scenes only. | | npx vfrey scene studio DIR [--port N] [--no-browser] | Opens an HTML scene in the visual editor (timeline, code, live preview) and saves edits back into DIR. Runs on 127.0.0.1 until Ctrl+C. See Scenes. | An HTML scene needs vfrey-framey or hyperframes. A React scene (index.tsx) needs remotion. A mismatch stops with a Fix: line. Blocks are for HTML scenes only. See Scenes and Scene blocks. npx vfrey scene --help lists init, blocks, add, transitions, inspect, and studio.

After a video

Command	What it does
`npx vfrey engage [--dry-run]`	Replies to comments on your published videos. With no platform keys the summary says “Replies skipped: no platform keys”.
`npx vfrey analytics [--dry-run]`	Collects view and like counts for published videos. The Metrics page shows only what the platforms returned. See Local desk.

Look

Command	What it does
`npx vfrey open [RUN_ID or VIDEO]`	The one command to run when you want to look. Reuses this project’s dashboard if it is running, else starts one in the background, opens your browser, and prints the URL. Give a run id, or a video’s path or title from `npx vfrey videos`, to open that run’s page. `--no-browser` prints the URL only. `--json` prints `{url, started, project, runId}`.
`npx vfrey videos`	Lists finished videos, newest first, as `date length title path`. `--limit N` shows the newest N. `--json` prints one document with the project (or `null`).
`npx vfrey dashboard`	Serves the dashboard in the foreground. The first line printed is its URL. If this project’s dashboard is already running, it prints that address and exits 0 instead of starting a second one. Without `--port` it uses the port it recorded last if free, else 4317, else the next free port. `--port PORT` forces a port. `dev` and `desk serve` are aliases.
`npx vfrey desk snapshot --json`	Prints the desk state for an agent.

Change the desk

Command	What it does
`npx vfrey desk series create\|update\|pause\|resume\|delete --id ID`	Manages a series. `update` takes `--engine ENGINE_ID` (or `default`), and the switches `--publish`, `--engage`, and `--review`, each `true` or `false`.
`npx vfrey desk series live --id ID --confirm CHANNEL_ID`	Takes a series out of dry-run. A new series is dry-run until you type its channel id here. `--off` returns it to dry-run with no confirm. See Autopilot.
`npx vfrey desk account create\|rename\|delete`, `secret set\|clear`, `platform set\|remove\|disable`, `source add\|update\|remove`, `cadence set`, `mode set\|clear`	Changes accounts, secrets (through stdin), platforms, sources, cadence, and mode.
`npx vfrey desk tick [--now] [--series ID]`	Ticks this project’s desk. The background worker runs this in each project.
`npx vfrey desk job approve --id JOB_ID`	Releases a job that waits for review. The next tick renders it.
`npx vfrey desk job reject --id JOB_ID [--reason TEXT]`	Ends a job that waits for review, as `rejected` with the code `review_rejected`.
`npx vfrey desk job retry --id JOB_ID`	Runs a failed job again.
`npx vfrey desk job cancel --id JOB_ID`	Cancels a stuck or running job.
`npx vfrey desk job delete --id JOB_ID`	Deletes a job.
`npx vfrey desk import --from ./data`	Merges an older folder.

A source kind is rss, subreddit, youtubeChannel, youtubeTrending, or vfrey-topics (paid). See Local desk and Autopilot.

Background service

Command	What it does
`npx vfrey service install`	Runs the worker in the background (launchd on macOS, systemd user unit on Linux) and starts it at login. Safe to run again.
`npx vfrey service uninstall`	Stops it and removes the file.
`npx vfrey service status [--json]`	The service state, the last cycle, and each project’s last tick and next due time.
`npx vfrey service logs [--follow]`	The last 50 lines of `~/.vfrey/logs/worker.log`. `--follow` keeps printing.

See Background worker.

Account

Command	What it does
`npx vfrey login [--api URL] [--no-browser]`	Signs in to your vfrey account. Only paid features need one.
`npx vfrey logout [--api URL]`	Revokes this machine’s token, then deletes it.
`npx vfrey whoami [--json] [--api URL]`	Shows your organization, plan, entitlements, credit balance, and this month’s usage. `VFREY_TOKEN` signs in without `login`.

Accounts are not live yet, so login and whoami say so and change nothing. See Account.

Teams and cloud

These commands need an account and the hosted vfrey service, which is not live yet. See Teams and cloud. Every one takes --api URL (the default is VFREY_API_URL).

Command	What it does
`npx vfrey org list [--json]`	Lists your organizations and marks the one this machine uses.
`npx vfrey org use ORG`	Switches this machine to another organization, by name or id. See Teams and roles.
`npx vfrey cloud link`	Connects this project, by its `vfrey.json` id, to a cloud project in your organization. Records `cloudProjectId`.
`npx vfrey cloud push [--videos] [--dry-run] [--json]`	Uploads changed scenes and scripts and the run details. `--videos` adds finished videos and transcripts. `--dry-run` sends nothing.
`npx vfrey cloud pull [--json]`	Downloads scenes and scripts changed in the cloud. If a file changed in both places, the newest wins and the other is kept as `FILE.conflict-TIME`.
`npx vfrey cloud status [--json]`	What is in sync, what to push, what to pull, and what conflicts.

See Cloud projects and sync.

Paid features

These commands need an account, a plan, and credits. The hosted vfrey service is not live yet, so they stop with “vfrey accounts are not live yet”. Every one takes --api URL (the default is VFREY_API_URL). See Plans and credits.

Command	What it does
`npx vfrey topics --niche ID [--limit N] [--since ISO] [--json]`	Ranked topics for a niche, with evidence links. Costs credits. `--limit` is 1 to 100. See Topics.
`npx vfrey topics niches [--json]`	Lists the niches. Needs the plan, no credits.
`npx vfrey topics request --name N --keywords a,b [--hashtags a,b] [--platforms tiktok,youtube]`	Asks for a new niche. Costs credits. It is collected on the next run.
`npx vfrey creators search [--niche ID] [--platform tiktok,youtube] [--followers 10k-200k] [--posts-per-week 3] [--engagement 4%] [--sort engagement\|growth\|views\|followers] [--limit N] [--json]`	Searches the creator index. See Creators.
`npx vfrey creators show @HANDLE --platform tiktok [--json]`	A creator’s profile, stats, formats, and hooks.
`npx vfrey creators watch add\|remove @HANDLE --platform tiktok [--watchlist NAME]`	Adds or removes a creator on a watchlist.
`npx vfrey creators watch list [--watchlist NAME] [--json]`	Lists watchlists, or the creators on one.
`npx vfrey creators export --watchlist ID > watchlist.csv`	Prints one watchlist as CSV, at most 500 rows.
`npx vfrey creators alerts [--json]`	Posts at 5 times a watched creator’s median views within 48 hours.
`npx vfrey mail draft --kind sponsor\|brand\|creator_collab\|client_update --need TEXT [--creator @HANDLE --platform tiktok] [--to EMAIL] [--to-name N] [--tone T] [--json]`	Writes a draft. Free. Sends nothing. See Mail.
`npx vfrey mail drafts [--status draft\|approved\|sent\|failed\|discarded] [--json]`	Lists drafts.
`npx vfrey mail show --id ID [--json]`	Prints one draft.
`npx vfrey mail approve --id ID`	A person approves one draft. Sends nothing. An agent asks the person first.
`npx vfrey mail send --id ID`	A person sends one approved draft, once. Charges one send. An agent asks the person first.
`npx vfrey mail discard --id ID`	Discards a draft.
`npx vfrey mail identity [--from-name N --reply-to EMAIL --postal-address A --org NAME] [--json]`	Shows or sets who mail is from. A new reply-to must be confirmed by a link before anything sends.

Set up and update

Command	What it does
`npx @vfrey/vfrey skill install [--agent claude\|codex\|grok\|cursor\|gemini\|all] [--project] [--dir PATH] [--force]`	Installs the skill on your machine, for working outside a project. A project already holds the skill. The default agent is Claude Code. `--project` installs into this folder’s skills folder (for example `./.agents/skills` for Codex) instead of your home folder. `--dir PATH` installs into `PATH/vfrey` for any other agent and does not combine with `--agent`. `--force` replaces a different copy. See Your agent.
`npx @vfrey/vfrey skill uninstall`	Removes the skill. Takes the same `--agent`, `--project`, and `--dir` flags.
`npx vfrey update`	Prints the update commands. It runs them only with `--apply`.
`npx vfrey push`	Refuses for now. Publishing happens inside `tick` once your keys are set.

Engines

Command	What it does
`npx vfrey engine list`	Shows each engine as ready or unavailable, with the reason, and the default. `--json` prints it for a machine.
`npx vfrey engine use ENGINE_ID`	Sets the machine default engine.
`npx vfrey tick --now --engine ENGINE_ID`	Renders this run with that engine. `render` takes `--engine` too.
`npx vfrey desk series update --id ID --engine ENGINE_ID`	Sets a series engine. `--engine default` follows the machine default.

The engine IDs are remotion (the default), vfrey-framey, hyperframes, and comfyui (not wired yet). The order is --engine, then the series, then the project’s vfrey.json, then the machine default. If the chosen engine cannot run, the job ends blocked with a Fix: line. There is no fallback. The Engine: line of the summary and --json say which engine rendered. See Engines. tick stops a video on a failed quality check and prints its Fix: line.

Not commands

Ingest is not a command. It ships inside the source stage of a run. The remote MCP server is not a command either.

Getting Started

Concepts

Paid features

Teams and cloud

Reference

Resources

Commands

Start a project

Make a video

Scenes

After a video

Look

Change the desk

Background service

Account

Teams and cloud

Paid features

Set up and update

Engines

Not commands

​Start a project

​Make a video

​Scenes

​After a video

​Look

​Change the desk

​Background service

​Account

​Teams and cloud

​Paid features

​Set up and update

​Engines

​Not commands

Start a project

Make a video

Scenes

After a video

Look

Change the desk

Background service

Account

Teams and cloud

Paid features

Set up and update

Engines

Not commands