Node.js 24 or later
The commands below use npx to run the latest CLI package. You can try it without a separate global installation.
VHS CLI / GET STARTED
Generation tools
for your terminal.
Use VHS CLI directly, in a script, or with a coding agent such as Codex or Claude Code.
The CLI handles sign-in, reference uploads, generation jobs, and saving the results. Models run on the VHS service. You sign in with your VHS account; individual provider API keys aren’t needed.
BEFORE YOU START
A few things to have installed.
ffmpeg and ffprobe
Make both commands available on your PATH. The CLI uses ffprobe to inspect references and ffmpeg when an output needs conversion to your chosen file format.
A VHS account
The login command opens your browser for Google sign-in. You can check your account and balance with the account command.
QUICK START
Make your first image.
Run these commands in your terminal. Once you’ve signed in, list the available models and choose one for your first generation.
generate submits the job, waits for it to finish, and saves the output to the path you provide.
Sign in and generate an image
npx @getvhs/vhscli@latest login
npx @getvhs/vhscli@latest models
npx @getvhs/vhscli@latest generate gpt-image-2 "a quiet courtyard, soft morning light" -o courtyard.png
The output is an ordinary file in your current directory. For a model’s inputs and settings, run npx @getvhs/vhscli@latest generate gpt-image-2 --help.
WITH YOUR CODING AGENT
Add the VHS skills.
The skills bundle gives your agent instructions for using VHS CLI. Run the installer from the project folder you use with your agent.
For Claude Code, create the .claude folder first so the skills can install where Claude Code looks.
Install the agent skills
mkdir -p .claude
npx skills add https://github.com/getvhs/vhscli-skills -y
Then describe the work.
For example: “Use VHS to generate three courtyard reference images with soft morning light. Save them in a references folder.” Your agent can use the CLI to run the jobs and collect the files.
Keep your direction close.
Tell the agent which references to use, where outputs should go, and what you want to change between takes. You can also ask it to inspect a model’s help before choosing settings.
A FEW USEFUL COMMANDS
From a prompt to a file.
| Command | What it does |
|---|---|
models
|
List the model aliases available to the CLI. |
generate
|
Submit one job, wait for it, and save the result. |
submit
|
Start a job and print its task ID without waiting. |
resume
|
Wait for a submitted task and save its output. |
poll / save
|
Watch several task IDs and save each result as it finishes. |
chat
|
Get a text reply, optionally with an image, video, or PDF input. |
account
|
Check your signed-in account and balance. |
Use a reference image.
Add -i to an image generation command. Other input flags depend on the model, so check its help before you start.
Generate with a reference
npx @getvhs/vhscli@latest generate gpt-image-2 "keep the courtyard, change the light to late afternoon" -i courtyard.png -o afternoon.png
Leave a job running.
Submit a task when your agent has other work to do. Keep the returned ID: it’s how you return to the same job.
Submit a generation
npx @getvhs/vhscli@latest submit gpt-image-2 "a quiet courtyard" -o courtyard.png
Then replace TASK_ID with the ID printed above:
Resume a submitted task
npx @getvhs/vhscli@latest resume TASK_ID -o courtyard.png
HELP & SOURCE
Keep exploring.
Run npx @getvhs/vhscli@latest --help for the full command list. Add --help after a command or model to see its exact options.
Need a hand getting started? Email [email protected].