vhscli
Generate or edit images and videos with AI via the `vhscli2` CLI. Use when the user wants AI images or videos, or mentions vhscli, vhs, seedream, seedance, nano-banana, gpt-image, or minimax.
How do I install this agent skill?
npx skills add https://github.com/getvhs/vhscli-skills --skill vhscliIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill enables the agent to interact with the vhscli2 CLI tool for generating AI media. It uses official packages from the vendor and includes security best practices for handling user input via stdin.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
vhscli2
vhscli2 generates images and videos with AI models in the cloud. It is a
thin client: auth, uploads, and model execution happen server-side, so no
provider API keys are stored locally. Every input and output is also kept in
the user's default VHS workspace (the Generate app at platform.getvhs.com).
It ships its own ffmpeg and ffprobe (always used from inside the package,
never from PATH), so formats are handled for you:
- Image inputs (
-i,--first-frame,--last-frame): JPEG/PNG up to 2048px per edge and 10MB are uploaded unchanged. Anything else (webp, avif, tiff, bmp, an animated file's first frame, ...) or anything larger is converted to JPEG (PNG stays PNG, so transparency is kept) and scaled down to fit 2048px. - Video inputs (
-v): up to 1920px per edge and 50MB are uploaded unchanged; larger ones are re-encoded to H.264.mp4that fits 1920px. - Audio inputs (
-a): uploaded unchanged, not converted. Stick to common formats (.mp3,.wav,.m4a,.aac,.ogg,.flac). - Output: the format follows the
-oextension, and the CLI converts the model's result if it differs. Images:.jpg/.jpeg,.png,.webp. Videos:.mp4,.webm,.mov.
Don't pre-convert or shrink images and videos yourself. Pass them as they are.
Invocation
Always run via npx, so you get the newest models and flags:
npx -y @getvhs/vhscli2@latest <command> ...
Commands below are written as vhscli2 ... for readability — substitute the
npx form when running. Don't call a bare vhscli2 binary even if one is on
PATH; it may be stale.
Runs on macOS arm64 and Windows x64 only. Requires Node.js ≥ 18.
Run vhscli2 generate <model> -h for a model's current flags — the CLI is the
source of truth.
Commands
vhscli2 login sign in (opens a browser)
vhscli2 generate <model> <prompt> -o <path> [flags] make an image or a video
vhscli2 models list the models
vhscli2 --version
Auth
Assume the user is already signed in. If a command fails with an auth error,
ask the user to run vhscli2 login (suggest
! npx -y @getvhs/vhscli2@latest login). It opens a browser, waits up to 5
minutes, and needs a person there. Don't run it yourself. The
session lives in ~/.vhs/session.json and is shared with vhscli and VHS
Studio, so signing in to any of them is enough.
Output and errors
- Flags can go anywhere among the arguments (before or after the prompt).
-o, the flags, and the reference counts are checked locally before anything is uploaded or charged. The-ofolder must already exist.- Inputs are uploaded to the user's default VHS workspace. Each file is stored once by content hash, so sending the same file again doesn't upload it a second time.
generateblocks until the result is saved. Progress goes to stderr; stdout is only the absolute path of the saved file.- On failure the exit code is 1 and stderr ends with
error: ...naming the step, the url, the server's answer and, once a generation has started, its request id. Report that line to the user. The CLI never retries on its own; if the error saysnetwork error, running it again may work. If it saysinsufficient balance, the user has to add credit at platform.getvhs.com. - If the generation succeeded but saving failed, the error includes the output url. It's signed for about an hour, so you can still download it.
- A successful run logs
cost: $Xon stderr. - Videos can take minutes — run them with a long timeout (or in the background). A video interrupted with ctrl-c still finishes server-side and shows up in the Generate app, but the CLI won't save it locally.
- To make several outputs at once, run several
generatecommands in parallel.
Prompts from stdin
Pass - as the prompt to read it from stdin — useful for long prompts or ones
with quotes:
cat prompt.txt | vhscli2 generate gpt-image-2.6-flare - -o art.png
Models
| Model | Kind | Pick it when |
|---|---|---|
seedream-5 | image | default image model — fast, 2K–3K, up to 14 refs |
seedream-5-pro | image | best detail/prompt adherence from seedream; ~2 min per image |
nano-banana-2.1 | image | Google; up to 4K; strong at edits ("remove X, keep everything else") |
nano-banana-pro | image | Google premium; better text rendering and richer textures |
gpt-image-2.6-flare | image | OpenAI, fast; text-heavy images, illustration, edits |
gpt-image-2.6-sunburst | image | OpenAI, detailed work; slower than flare |
seedance-2 | video | default video model; 480p–4k, 4–15s |
seedance-2.5 | video | longer (up to 30s) or many refs (30 img / 10 vid / 10 audio); max 1080p |
minimax-h3 | video | MiniMax; 480p/768p/2k; always has audio; cite refs as "Image 1", "Audio 1" |
vhscli2 models prints the current list.
Image models
All six image models share the same flags:
vhscli2 generate <image-model> <prompt> -o <path> [-i <image>...] [--size <WxH>]
-o,--output <path>— required;.jpg,.png, or.webp-i,--image <path>— reference image; repeat for more. Up to 14 for seedream and nano-banana. Use them to guide style, characters, or composition — or as the image to edit.--size <width>x<height>— default1920x1080. One value carries both the aspect ratio and the resolution, e.g.1024x1024,1080x1920,3840x2160. Each edge must be 64–4096. The server fits the size to the provider and renders the closest frame it can, so it never refuses a size, but what comes back may differ a little from what you asked for.
Per-model notes:
- seedream-5 / seedream-5-pro — won't render a small frame: anything under
about 2K is scaled up, so
960x540comes back as roughly2560x1440.-protakes ~2 minutes; use it when the user asks for top quality orseedream-5keeps missing details in a complex prompt. - nano-banana-2.1 / nano-banana-pro — up to 4K, up to 14 refs. Good at
targeted edits.
-prohandles text in images and textures better. - gpt-image-2.6-flare / -sunburst —
-iimages are edited or composed from (there's no fixed reference cap).flareis fast,sunburstis for detailed work. Use a.pngoutput when you need transparency (and pass PNG inputs to keep theirs).
Editing an image: pass it with -i and say what to change and what to
keep ("remove the man, keep everything else").
Examples:
vhscli2 generate seedream-5 "a corgi astronaut riding a bicycle on mars" -o corgi.jpg
vhscli2 generate seedream-5 "remove her hat, keep everything else" -i photo.jpg -o edit.png
vhscli2 generate seedream-5-pro "a lone lighthouse on a cliff at dusk, long exposure, crashing surf" -o lighthouse.png
vhscli2 generate nano-banana-2.1 "remove the man from the photo, keep everything else" -i photo.jpg -o clean.png
vhscli2 generate nano-banana-pro "a sun-drenched minimalist living room with a 3d armchair from this sketch" -i sketch.jpg -o room.png
vhscli2 generate nano-banana-pro "90s skateboarder poster, vertical composition" --size 1080x1920 -o poster.png
vhscli2 generate gpt-image-2.6-flare "a children's book drawing of a veterinarian examining a cat" -o vet.png
vhscli2 generate gpt-image-2.6-sunburst "replace the background with a starry night" -i photo.jpg -o night.png
vhscli2 generate gpt-image-2.6-sunburst "ultra-wide landscape of the swiss alps at golden hour" --size 3840x2160 -o alps.jpg
Video models
All three video models share this shape:
vhscli2 generate <video-model> <prompt> -o <path>
[--first-frame <image>] [--last-frame <image>]
[-i <image>...] [-v <video>...] [-a <audio>...]
[--ratio <r>] [--resolution <res>] [--duration <n>]
Mode is picked from your flags:
- prompt only → text-to-video
--first-frame→ animate from that image (optionally ending on--last-frame)-i/-v/-a→ reference-based generation
Flags:
-o,--output <path>— required;.mp4,.webm, or.mov(prefer.mp4)--first-frame <image>— use as the first frame--last-frame <image>— use as the last frame (needs--first-frame)-i,--image <path>— reference image; repeatable; conflicts with--first-frame-v,--video <path>— reference video; repeatable; conflicts with--first-frame-a,--ref-audio <path>— reference audio; repeatable; needs-ior-v; conflicts with--first-frame--ratio <r>—21:9,16:9,4:3,1:1,3:4,9:16(default16:9)--resolution <res>— per model, below (lowercase)--duration <n>— seconds, per model, below (default 5)--no-audio— silent video (seedance only)
seedance-2 | seedance-2.5 | minimax-h3 | |
|---|---|---|---|
--resolution | 480p, 720p, 1080p, 4k | 480p, 720p, 1080p | 480p, 768p, 2k |
--duration | 4–15 | 4–30 | 4–15 |
| refs (img / vid / audio) | 9 / 3 / 3 | 30 / 10 / 10 | 9 / 3 / 3, ≤12 total |
| audio | on; --no-audio for silent | on; --no-audio for silent | always on (no --no-audio) |
Per-model notes:
- seedance-2 — the default. The only choice for 4k.
- seedance-2.5 — for clips longer than 15s or when you need many references. Tops out at 1080p.
- minimax-h3 — always renders its own audio track. Cite references in the
prompt by modality and list order: "Image 1", "Video 1", "Audio 1".
Reference videos and audios must be 2–15s each. With
--first-framethe output follows the input image's frame, so passing--ratiothere is an error.
Examples:
# text-to-video
vhscli2 generate seedance-2 "a robot dancing in tokyo at night, slow tracking shot" -o robot.mp4
vhscli2 generate seedance-2 "a cat jumping off a couch" -o cat.mp4 --duration 6 --ratio 9:16
# animate a still
vhscli2 generate seedance-2 "animate this photo: gentle pan to the right" --first-frame photo.jpg -o pan.mp4
# first and last frame
vhscli2 generate seedance-2 "morph between these" --first-frame a.jpg --last-frame b.jpg -o morph.mp4
# 4k, silent
vhscli2 generate seedance-2 "aerial shot over a misty pine forest at sunrise" --resolution 4k --no-audio -o forest.mp4
# long clip
vhscli2 generate seedance-2.5 "a woman in a red dress walks through a rainy neon-lit alley, slow tracking shot" --duration 20 --resolution 1080p -o alley.mp4
# references with audio
vhscli2 generate seedance-2 "lip sync the words" -i face.jpg -a voice.mp3 -o talk.mp4
vhscli2 generate minimax-h3 "Image 1 is the singer. She sings along to Audio 1 on a rooftop at dusk" -i singer.jpg -a song.mp3 -o rooftop.mp4
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/getvhs/vhscli-skills/vhscli">View vhscli on skillZs</a>