DOCSEARCHbyAlgolia
Submit Docs

Higgsfield CLI Documentation

repository·main·Indexed 19 days ago

https://github.com/higgsfield-ai/cli

A terminal-based interface for accessing over 40 Higgsfield AI models to generate images, videos, 3D assets, and audio. The CLI supports complex video workflows, Soul ID character training, browser-based game deployment, and the provisioning of full-stack React 19 + TanStack Start websites deployed as Cloudflare Workers.

Tokens
7.8K
Snippets
28
Records
32
Agent score
15%

What's inside Higgsfield CLI

  1. Use Higgsfield Workflows

    main

    Workflows are high-level generation flows (like dubbing or reframing) that have unique parameter schemas.

    1. Discover workflows: higgsfield workflow list
    2. Inspect parameters: higgsfield workflow get <workflow_name>
    3. Run a workflow: Use higgsfield generate workflow <workflow_name> followed by the required flags.
    4. Estimate cost: Use higgsfield generate cost workflow <workflow_name> for supported workflows.
    # List available workflows
higgsfield workflow list

# Inspect parameters for 'reframe'
higgsfield workflow get reframe --json

# Run a 'reframe' workflow
higgsfield generate workflow reframe \
  --video ./source.mp4 \
  --aspect-ratio 9:16 \
  --resolution 720p \
  --wait

# Estimate cost for 'draw_to_video'
higgsfield generate cost workflow draw_to_video --duration 8.2 --resolution 720p

  2. How to use media inputs in Higgsfield CLI

    main

    When using Higgsfield CLI models, media input flags such as --image, --image-references, --start-image, --end-image, --video, --video-references, --audio, and --audio-references accept two types of values:

    1. A UUID (representing an existing upload ID or a previous job ID).
    2. A local file path. If a path is provided, the CLI will automatically upload the file for you.

    Note that many models allow multiple image references (e.g., using the --image flag repeatedly), while others are constrained to a single image or a specific maximum count.

  3. Configure website types and templates

    main

    When using higgsfield website create, you must specify the --type and --category.

    Website Types

    • website: A standalone site with no Higgsfield integration (e.g., landing pages, portfolios).
    • app: A product tightly integrated with Higgsfield. Users sign in with Higgsfield and use the Higgsfield SDK to generate media. Requires a --template.

    App Templates

    If --type app is selected, you must choose one of the following templates:

    • app-detail: A single tool's public landing page with a generator hero.
    • preset: Pick-a-style generation, preset galleries, or wizards.
    • studio: A full creative workspace with projects, prompt dock, and a generations feed.
    • custom: A bare scaffold with no shipped layout (use only when explicitly requested).

    Categories

    Every site requires a --category slug from a curated taxonomy (e.g., cinematic, ads-marketing, ugc-social). Run higgsfield website categories to see the full list. Use other if no specific category fits.

    # Create a standalone website
higgsfield website create --type website --category other

# Create an integrated app with a preset template
higgsfield website create \
  --type app \
  --category ads-marketing \
  --template preset \
  --subdomain my-app

  4. Quickstart: Authenticate and Generate an Image

    main

    To start using the CLI, first authenticate your session. Once authenticated, you can generate content using the higgsfield generate create command. Using the --wait flag will cause the command to block until the result URL is available.

    # Authenticate
higgsfield auth login

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

  5. Train and use Soul IDs

    main

    Soul IDs allow you to train a face-faithful character that can be reused across compatible models.

    1. Train: Use higgsfield soul-id create with multiple images of the subject.
    2. Wait: Use higgsfield soul-id wait <soul_id> to monitor training progress.
    3. Reuse: Pass the <soul_id> to compatible models like text2image_soul_v2 using the --soul-id flag.
    # Train a Soul ID
higgsfield soul-id create --name me --soul-2 \
  --image ./me1.jpg --image ./me2.jpg --image ./me3.jpg

# Wait for training
higgsfield soul-id wait <soul_id>

# Reuse in image generation
higgsfield generate create text2image_soul_v2 \
  --prompt "professional portrait, neutral background, soft daylight" \
  --soul-id <soul_id> \
  --wait

  6. Build and deploy full-stack websites with `higgsfield website`

    main

    The higgsfield website command allows you to provision, develop, and deploy full-stack React 19 + TanStack Start applications. These sites are server-rendered as Cloudflare Workers and can utilize D1, R2, KV, Durable Objects, and Containers.

    Workflow

    1. Create: Provision a site and a git repository using higgsfield website create.
    2. Access: Use higgsfield website repo-access <website_id> to get clone credentials.
    3. Develop: Clone the repo, edit code in the app/ directory, and push changes using a scoped git token.
    4. Deploy: Run higgsfield website deploy <website_id> to push the site live.
    5. Publish: (Optional) Use higgsfield website publish <website_id> to list the site on the Higgsfield community feed.

    Important Development Notes

    • Runtime: The scaffolded repositories use Bun. Use bun install, bun add, bunx, and bun run. Do not use npm, npx, or yarn.
    • Code Structure: Edit files under app/. Do not hand-edit app/src/routeTree.gen.ts as it is auto-generated.
    • Subdomains: Use --subdomain during creation to set a DNS-safe slug. Renaming a subdomain via higgsfield website rename will cause the old URL to stop working immediately.
    # 1. Create the site
higgsfield website create --type website --category other

# 2. Get access
higgsfield website repo-access <website_id>

# 3. Clone and push (example using git extraHeader for token)
git -c http.extraHeader="Authorization: token <token>" clone <repo_url> <slug>
cd <slug>
git config user.email "agent@higgsfield.ai" && git config user.name "Higgsfield Agent"
# ... edit files in app/ ...
git add -A && git commit -m "initial build"
git -c http.extraHeader="Authorization: token <token>" push origin <branch>

# 4. Deploy
higgsfield website deploy <website_id>

  7. Install the Higgsfield CLI

    main

    You can install the Higgsfield CLI using several methods depending on your platform.

    macOS / Linux (curl)

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

    macOS / Linux (Homebrew)

    brew update && brew upgrade higgsfield

    Cross-platform (npm)

    npm install -g @higgsfield/cli@latest

    Pin to a specific version

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

# Using npm
npm install -g @higgsfield/cli@1.1.2

  9. Generate content using specific models

    main

    The CLI supports over 40 models across Image, Video, 3D, and Audio categories. Use higgsfield generate create <job_set_type> to start a job.

    Common examples include:

    • Nano Banana Pro: High-quality image generation.
    • GPT Image 2: Infographic and clean icon generation.
    • Kling v3.0: Video generation from text or images.
    • Seedance 2.0: High-resolution drone-style video generation.
    • Virality Predictor: Analyzes video for engagement potential (uses brain_activity job type).
    # Nano Banana Pro
higgsfield generate create nano_banana_2 \
  --prompt "modern architecture, glass facade, golden hour light" \
  --aspect_ratio 16:9 \
  --resolution 2k \
  --wait

# Kling v3.0
higgsfield generate create kling3_0 \
  --prompt "slow camera push through a forest clearing at dawn" \
  --start-image ./first.png \
  --duration 5 --mode pro --sound off \
  --wait

# Virality Predictor
higgsfield generate create brain_activity --video ./ad.mp4 --wait

  10. Deploy and Publish Games

    main

    The CLI allows you to deploy browser-based games from a ZIP archive. The ZIP must contain an index.html and either logic.js or server.js at its root.

    • Deploy: higgsfield game deploy <path_to_zip>
    • Update: Use the --game-id <game_id> flag with the deploy command to update an existing game.
    • Publish: Use higgsfield game publish <game_id> to make the game available in the marketplace.
    # Deploy a new game
higgsfield game deploy ./game.zip \
  --title "Space Runner" \
  --description "Fast arcade survival game" \
  --thumbnail https://cdn.example/cover.png \
  --favicon https://cdn.example/icon.png \
  --json

# Publish to marketplace
higgsfield game publish <game_id> --name "Space Runner" --json

  11. Generate speech with text2speech_v2

    main

    The text2speech_v2 job converts text to speech using various engines.

    Available Variants: elevenlabs, minimax, seed_speech, vibe_voice, cozy_voice.

    Engine Character Limits:

    • elevenlabs, vibe_voice, cozy_voice: 5000 characters
    • minimax: 10000 characters
    • seed_speech: 15000 characters

    Use higgsfield voices list to discover available --voice_id and --voice_type combinations.

    # higgsfield generate create text2speech_v2 --prompt "Hello from Higgsfield" --variant elevenlabs --voice_type preset --voice_id <voice_id> --wait

  12. Manage website databases and secrets

    main

    You can inspect and manage the backend resources of your hosted websites using the following commands:

    Database Management (Read-Only)

    • List tables: higgsfield website db tables <website_id>
    • View rows: higgsfield website db rows <website_id> --table <table_name> --limit <number>
    • Run SQL queries: higgsfield website db query <website_id> --sql "<SQL_QUERY>"

    Secret Management

    Secrets are staged and only take effect after the next deploy.

    • Set a secret: higgsfield website secrets set <website_id> --name <KEY> --value <VALUE>
    • List secrets: higgsfield website secrets list <website_id>
    higgsfield website db query <website_id> --sql "SELECT count(*) FROM users"
higgsfield website secrets set <website_id> --name STRIPE_SECRET_KEY --value sk_live_...