Run Higgsfield CLI

Run Higgsfield CLI is a free agent skill maintained by Scopeful. It teaches an AI coding agent such as Claude Code, Cursor, Windsurf or Codex how to drive this tool correctly, so you do not have to re-explain it every session. Every published Scopeful skill is free and the install command is public, with no sign-in required. Install it with npm install -g @higgsfield/cli. Scopeful also tracks hand-verified USD pricing for 39 AI creative tools at https://www.scopeful.org/tools.

Install + auth + command reference for @higgsfield/cli. 30+ models, 4 workflows, Marketing Studio, Virality Predictor, Soul training, voices.

Tags: video, image, cli, higgsfield, marketing-studio, virality-predictor

Install

npm install -g @higgsfield/cli

Reference

name: higgsfield-cli description: Use this skill whenever the user wants to install, authenticate, or run the Higgsfield CLI (@higgsfield/cli) for image, video, 3D, or audio generation. Triggers include any mention of "Higgsfield CLI", higgsfield generate, higgsfield auth login, npm install -g @higgsfield/cli, brew install higgsfield-ai/tap/higgsfield, or asking an agent to run a generation from the terminal. Do not trigger for the consumer mobile app or for installs that only need the MCP — that is the higgsfield-mcp skill.

Run the Higgsfield CLI

Higgsfield publishes a real binary at @higgsfield/cli (npm) and higgsfield-ai/tap/higgsfield (Homebrew). It wraps 30+ image / video / 3D / audio models, Marketing Studio (branded ads), Virality Predictor (video scoring), 4 workflows (draw_to_video, reframe, voice-change, dubbing), Soul character training, and voices. This skill is the install + command reference; it does not teach prompt structure or model selection (that is the higgsfield-mcp-better master skill).

Verified facts (live 2026-06-30)

• npm install -g @higgsfield/cli resolves to @higgsfield/cli@1.0.1 (published 2026-06-27, 371 stars, MIT).
• The npm package ships two bin entries: higgsfield (primary) and higgs (always-on alias).
• The curl installer (higgsfield-ai/cli/install.sh) installs the same binary plus an optional hf shortcut unless something else already owns that name.
• Homebrew tap higgsfield-ai/tap/higgsfield is the macOS path.
• higgsfield auth login is the only auth command; the CLI opens a browser, you confirm, token is stored locally.
• Tokens are short-lived; higgsfield account status after 24h+ will print Session expired and you re-run higgsfield auth login.

Install

Pick the path that matches the OS. All three install the same higgsfield binary.

macOS / Linux — curl (universal)

curl -fsSL https://raw.githubusercontent.com/higgsfield-ai/cli/main/install.sh | sh

Pin to a specific tag:

curl -fsSL https://raw.githubusercontent.com/higgsfield-ai/cli/main/install.sh | sh -s -- --tag v1.0.1

Install to a user prefix when sudo is not available:

curl -fsSL https://raw.githubusercontent.com/higgsfield-ai/cli/main/install.sh | sh -s -- --prefix=$HOME/.local
# then ensure $HOME/.local/bin is on $PATH

macOS — Homebrew

brew install higgsfield-ai/tap/higgsfield

Windows + cross-platform — npm

npm install -g @higgsfield/cli

Verify

higgsfield version
# expect: higgsfield v1.0.1 (...) built ...
higgsfield account status
# before auth: Not authenticated
# after auth:  <email> — <plan> plan, <N> credits

Auth

higgsfield auth login

Opens a browser. Confirm. Token is stored locally. Sessions are short-lived — re-run on Session expired.

higgsfield auth logout clears the token. higgsfield account shows balance + recent transactions. higgsfield workspace list / select / unset switches the billing workspace if the user belongs to one.

Quickstart

# Generate an image and wait for the result URL on stdout
higgsfield generate create nano_banana_2 \
  --prompt "a quiet beach at sunrise" \
  --wait

# Image-to-video with motion preset
higgsfield generate create seedance_2_0 \
  --prompt "camera dollies in" \
  --start-image ./first.png \
  --duration 5 --resolution 1080p \
  --wait

# Branded UGC ad via Marketing Studio
higgsfield marketing-studio products fetch --url https://shop.example.com/sneakers --wait
higgsfield generate create marketing_studio_video \
  --url https://shop.example.com/sneakers \
  --mode ugc --duration 15 --aspect_ratio 9:16 \
  --wait

# Score a finished ad with Virality Predictor
higgsfield generate create brain_activity --video ./ad.mp4 --wait

--wait blocks until the job finishes and prints the result URL on stdout. Default wait timeout is 10 minutes; bump with --wait-timeout 30m for long ad runs. Default poll interval is 3s; tune with --wait-interval 5s. Add --json for machine-readable output (chains + agent context).

Commands (the ones you will use)

Run higgsfield <command> --help (or higgsfield generate create --help) for flags + examples.

Models (the 30+ catalog)

higgsfield model list is always the live source — run it before assuming a slug exists. The current shape (2026-06-30):

Image (21): nano_banana_2, nano_banana_flash, nano_banana, flux_2, flux_kontext, gpt_image_2, text2image_soul_v2, seedream_v4_5, seedream_v5_lite, grok_image, openai_hazel, outpaint, recraft_v4_1, image_auto, image_background_remover, z_image, kling_omni_image, cinematic_studio_2_5, soul_cinematic, soul_location, marketing_studio_image.

Video (20): brain_activity (Virality Predictor), veo3_1, veo3_1_lite, veo3, kling3_0, kling3_0_turbo, kling2_6, seedance_2_0, seedance1_5, wan2_7, wan2_6, minimax_hailuo, grok_video, grok_video_v15, cinematic_studio_3_0, cinematic_studio_video, cinematic_studio_video_v2, soul_cast, marketing_studio_video, video_background_remover.

3D (1): multi_image_to_3d — 1 to 4 reference images, returns a GLB.

Audio (3): sonilo_music, mirelo_text_to_audio, text2speech_v2 (5 engines: elevenlabs, minimax, seed_speech, vibe_voice, cozy_voice).

Workflows (the 4)

higgsfield workflow list is the live catalog. The current shape:

• draw_to_video — edit a source clip with a sketch frame at a timestamp.
• reframe — re-aspect a source video (9:16, 1:1, etc.) with optional target resolution.
• voice-change — replace the voice on a source video with a chosen voice.
• dubbing — dub a source video into another language (--target_language is ISO-639-3: eng, spa, fra, deu, jpn, …).

Create through higgsfield generate workflow <name> ... --wait. Estimate cost through higgsfield generate cost workflow <name> ... (not supported for voice-change or dubbing).

Media inputs (the bit agents always get wrong)

Media flags accept a local file path (auto-uploaded) or a UUID (upload id from higgsfield upload create OR a previous job id). Do not pre-upload unless you are reusing the same media in many jobs.

Live feedback (the part agents skip)

• Always pass --wait. It blocks until the job reaches a terminal state and prints the result URL on stdout. The two-step create then wait pattern just doubles the round-trips.
• For long pipelines, add --json so the next command in your chain can jq the result. With --wait --json you get the final job object array; without --wait, you get the job IDs.
• Stdin prompt: echo "..." | higgsfield generate create z_image --wait.
• For failed renders, read the message; do not retry blindly. Session expired -> higgsfield auth login. Invalid values: aspect_ratio=99:99 (allowed: ...) -> pick from the allowed enum. Missing required params: medias on brain_activity -> pass exactly one --video. Unknown params: foo -> the schema does not accept that flag; run higgsfield model get <jst> to see what it does accept.

Updating

# curl
curl -fsSL https://raw.githubusercontent.com/higgsfield-ai/cli/main/install.sh | sh

# brew
brew update && brew upgrade higgsfield

# npm
npm install -g @higgsfield/cli@latest

Uninstall

# curl install (default prefix /usr/local)
sudo rm /usr/local/bin/higgsfield /usr/local/bin/higgs

# brew
brew uninstall higgsfield

# npm
npm uninstall -g @higgsfield/cli

Troubleshooting

• Session expired / Not authenticated — re-run higgsfield auth login.
• Unknown model "<name>" — run higgsfield model list for the current catalog. Do not guess slugs.
• Render produces a different model than expected — the model picker defaults change; check higgsfield model list and pass --model <jst> explicitly.
• higgsfield not found after install — the install prefix is not on $PATH. For the user prefix install, add $HOME/.local/bin to your shell rc; for /usr/local, ensure /usr/local/bin is on $PATH.

When NOT to use the CLI

• The user wants the agent to call Higgsfield without the user seeing any terminal commands. Use the MCP (higgsfield-mcp skill) instead.
• The user wants to render from inside a server-side pipeline that already has the @higgsfield/client TS SDK installed. Use the SDK directly; it is subscribe() + withPolling: true and it covers the same model surface.
• The user is on a phone or in the Higgsfield mobile app. The CLI is desktop-only.

Where to go next

• The higgsfield-mcp skill: connect the same models to any agent via the HTTP MCP at https://mcp.higgsfield.ai/mcp.
• The higgsfield-mcp-better master skill: model selection, prompt structure, Marketing Studio modes, Virality Predictor scoring, and the polling / failure playbook.