How do I install Higgsfield CLI?
One command. Three options for your shell.
Step 1: Install via curl, brew, or npm
bash
# curl (any Unix)
curl -fsSL https://raw.githubusercontent.com/higgsfield-ai/cli/main/install.sh | sh
# Homebrew (macOS / Linux)
brew update && brew install higgsfield-ai/tap/higgsfield
# npm (cross-platform, needs Node 18+)
npm install -g @higgsfield/cli@latest
The official repo is github.com/higgsfield-ai/cli.
Step 2: Add your API key
Get a key from higgsfield.ai/cli — sign up is free, generations are pay-as-you-go.
bash
higgsfield login
# paste your API key when prompted
Step 3: Generate your first image
bash
higgsfield image generate \
--model nano-banana-2 \
--prompt "cinematic lens flare, golden hour, woman walking on a Tokyo street" \
--aspect 9:16 \
--output ./hero.png
Step 4: Generate video from an image
bash
higgsfield video generate \
--model seedance-2 \
--image ./hero.png \
--motion "slow walk forward, hair blowing in wind" \
--duration 5 \
--output ./hero.mp4
Step 5: Wire it into Claude Code
In a Claude Code session, just describe what you want:
> "Generate a 5-second seedance loop from product.png with a slow zoom"
Claude calls higgsfield video generate directly because it sees your shell. You stay in your editor; assets land on disk.
What is Higgsfield CLI?
Higgsfield CLI is a single command-line interface to 30+ image and video generation models including Nano Banana 2, Soul V2, Veo 3.1, Kling 3.0, Seedance 2.0, Flux 2, and GPT Image 2. The official repo is github.com/higgsfield-ai/cli.
The pitch from Higgsfield's site: "AI Image & Video Generation for Any Agent". The point is agentic workflows — Claude Code, Cursor, custom scripts — that need to generate assets without opening a browser.
Is Higgsfield CLI really free?
The CLI itself is free. The generations are paid per call — you bring your own API key from your Higgsfield account. There is no monthly subscription, you pay per image or per second of video at the model's rate.
This is the honest part: Higgsfield is not a "free tool replaces paid tool" story. It is a "stop clicking, start scripting" story. If you only need a few images per week, Open Generative AI or Wan2GP run free on your machine.
How is Higgsfield CLI different from clicking through SaaS dashboards?
Three big differences:
- Composability. Claude Code or any agent can call the CLI directly because it speaks shell. No browser puppeteering, no API SDK wrangling.
- One key, many models. Instead of separate accounts on Runway, Pika, Veo, and Seedance, you point one key at 30+ models and pick at runtime.
- Reproducibility. The exact command that made an asset is in your shell history. Re-run with a different prompt, batch with bash, drop into a Makefile.
The community's unofficial Python wrapper and the growing pipeline guides suggest the agent crowd is adopting it fast.
What's the catch?
- Pay-per-generation. Higgsfield is not free. If you generate hundreds of images a day, run Open Generative AI or Wan2GP on your own GPU instead.
- Quality varies by underlying model. Veo 3.1 is excellent. Some of the cheaper models are not. Pick deliberately.
- Node 18+ requirement for the npm install path. If you are on an old box, use the curl install instead.
Bottom line
Higgsfield CLI is the right tool when you want one command-line interface to many premium models and you are running agentic pipelines. It is not a free local replacement — for that, run Wan2GP or Open Generative AI. Use Higgsfield CLI when speed and quality matter more than cost-per-generation.
Related Nanoflow guides
Want a hand?
Book a 30-min call.
Walk through your stack with us. We'll find the bottleneck and map out the exact wiring you need — free.