FoxCut CLI

AI image and video generation from your terminal.

FoxCut CLI is the official command-line client for FoxCut, a hosted creative automation platform built around the Model Context Protocol (MCP). It gives developers, coding agents, CI jobs, and shell scripts one authenticated interface for AI image generation, text-to-video, image-to-video, talking avatars, product photography, marketing videos, and reusable creative workflows.

Use it to discover current models and presets, estimate credit costs, upload private source media, start generations, and monitor asynchronous jobs—all with structured JSON output that is easy for humans and agents to consume.

Why FoxCut CLI?

• One CLI for a full creative pipeline: generate images, directed video, speech, product photography, UGC, and campaign assets.
• Designed for agents and automation: commands return JSON; --compact produces single-line output for scripts and tool loops.
• Hosted MCP tool access: call convenient first-class commands or invoke any available FoxCut MCP tool by name.
• Secure account connection: browser-based OAuth with Authorization Code, PKCE, token refresh, and revocation—no FoxCut API key to copy into a script.
• Cost-aware generation: inspect your credit balance and estimate a job before starting billed work.
• Private media workflow: upload local references, products, portraits, video, or audio to your own FoxCut library.

Requirements

• Node.js 20 or newer
• A FoxCut account

Install

Install globally with npm:

npm install --global @foxcut/cli

Or run it once without a global install:

npx @foxcut/cli --help

Quick start

Connect your FoxCut account in the browser, check your balance, and inspect the available generation models:

foxcut auth login
foxcut account status
foxcut models list

Create an image:

foxcut generate image --json '{
  "prompt": "A sculptural amber perfume bottle on warm travertine, late-afternoon shadows, restrained luxury editorial photography",
  "model": "soul",
  "aspect_ratio": "4:5",
  "quality": "high"
}'

Generation is asynchronous. Save the returned job ID and poll it until it succeeds, fails, or is canceled:

foxcut generation get JOB_ID

What you can build

FoxCut exposes creative building blocks that work alone or as part of an automated content pipeline:

• Text-to-image generation and reference-based image editing
• Text-to-video, image-to-video, and directed camera motion
• Talking avatars and lip-synced speech video
• Product shots, lifestyle scenes, hero banners, and social carousels
• UGC, unboxing, product showcase, review, TV spot, and virtual try-on concepts
• Brand kits, marketplace cards, video explainers, and YouTube thumbnails
• Character-consistent campaign assets and reusable moodboards
• Media editing, restyling, upscaling, importing, and private uploads

Run foxcut tools list to see the tool surface currently available to your account.

Common commands

| Task | Command | | --- | --- | | Connect an account | foxcut auth login | | Check the connection | foxcut auth status | | Disconnect and revoke access | foxcut auth logout | | View plan and credits | foxcut account status | | List MCP tools | foxcut tools list | | List generation models | foxcut models list | | List workflows | foxcut workflows list | | List style and motion presets | foxcut presets list | | List voices | foxcut voices list | | Upload local media | foxcut media upload FILE | | Generate an image | foxcut generate image --json JSON | | Generate a video | foxcut generate video --json JSON | | Generate avatar speech | foxcut generate speech --json JSON | | Run a product photoshoot | foxcut photoshoot --json JSON | | Create a marketing video | foxcut marketing-video --json JSON | | Inspect a generation | foxcut generation get JOB_ID | | List generations | foxcut generation list | | Cancel a generation | foxcut generation cancel JOB_ID | | Call any MCP tool | foxcut tool call NAME --json JSON |

Use foxcut --help for the complete command summary and the CLI reference for detailed inputs.

Generation examples

Create an AI image

foxcut generate image --json '{
  "prompt": "A modern trail shoe suspended over red mineral dust, hard side light, premium campaign photography",
  "model": "soul",
  "aspect_ratio": "1:1",
  "color_palette": ["#F9663F", "#FC9934", "#F53349"],
  "batch_size": 2,
  "quality": "high"
}'

Image generation supports negative prompts, source images, up to eight references, style presets, moodboards, exact color palettes, trained characters, batch generation, quality control, and deterministic seeds.

Create an AI video

foxcut generate video --json '{
  "prompt": "A slow cinematic push toward a translucent orange sculpture as morning light moves across the room",
  "model": "foxcut-dop",
  "duration_seconds": 5,
  "aspect_ratio": "9:16",
  "resolution": "720p",
  "motion_strength": 0.55,
  "quality": "high"
}'

Add start_image_url for image-to-video, end_image_url for last-frame control, or reference_video_url for supported motion-transfer workflows. Use foxcut presets list --type motion to discover current camera and motion presets.

Upload a product and run a photoshoot

foxcut media upload ./product.png --purpose product

Use the managed URL returned by the upload:

foxcut photoshoot --json '{
  "product_image_url": "MANAGED_PRODUCT_URL",
  "shot_mode": "hero_banner",
  "direction": "A bold studio launch image with sculptural shadows and generous negative space for copy",
  "model": "soul",
  "aspect_ratio": "16:9",
  "batch_size": 2
}'

Supported local uploads include PNG, JPEG, WebP, MP4, MP3, and WAV files. Set --purpose to reference, product, avatar, or audio.

Create a talking avatar

foxcut generate speech --json '{
  "portrait_url": "MANAGED_PORTRAIT_URL",
  "script": "Meet the creative workflow that moves as quickly as your ideas.",
  "model": "foxcut-speak",
  "voice_id": "aria",
  "resolution": "1080p",
  "aspect_ratio": "9:16"
}'

List available voices first with foxcut voices list.

Cost-aware automation

Generative commands spend FoxCut credits. Read-only discovery and estimation commands do not. Before starting a material job or batch, check the account and estimate the expected cost:

foxcut account status

foxcut tool call estimate_generation_cost --json '{
  "kind": "t2v",
  "model": "foxcut-dop",
  "params": {
    "durationSec": 5,
    "aspect": "9:16",
    "resolution": "720p",
    "quality": "high"
  }
}'

For unattended automation, preserve every returned job ID. Poll with foxcut generation get JOB_ID; never infer a successful output URL before the job reports completion.

Agent and script usage

Every command returns machine-readable JSON. Add --compact anywhere in the command to emit one line:

foxcut models list --type video --compact
foxcut generation list --status running --limit 10 --compact

The generic MCP bridge lets an agent access newly added tools without waiting for a dedicated CLI alias:

foxcut tools list
foxcut tool call TOOL_NAME --json '{"input": "value"}'

This makes the CLI suitable for coding-agent skills, CI pipelines, shell automation, and backend jobs that need a stable command boundary instead of a custom SDK integration.

Authentication and security

foxcut auth login uses OAuth discovery, dynamic client registration, Authorization Code with PKCE S256, refresh tokens, and token revocation. The CLI opens the FoxCut authorization page; your account password is never entered into the CLI.

Credentials are stored with owner-only permissions at:

~/.config/foxcut/config.json

If XDG_CONFIG_HOME is set, the file is stored beneath that directory instead. Set FOXCUT_CONFIG_DIR to use an isolated configuration root for a container or automation environment.

Disconnect and revoke the active credential with:

foxcut auth logout

Remote machines and development containers

When the browser and CLI run on different machines, use manual callback mode:

foxcut auth login --manual

After approving access, FoxCut shows a callback URL. Paste it into the waiting CLI. The CLI still validates the callback address and OAuth state before completing the PKCE exchange.

Set FOXCUT_NO_BROWSER=1 if you want the CLI to print the authorization URL without attempting to launch a browser.

Self-hosted development

The CLI connects to https://foxcut.ai by default. To work against a local FoxCut server:

foxcut auth login --server http://localhost:3000

You can also set the server for login through the environment:

FOXCUT_SERVER=http://localhost:3000 foxcut auth login

The server must expose FoxCut's MCP endpoint and OAuth discovery flow.

Troubleshooting

FoxCut is not connected

Run foxcut auth login, then verify with foxcut auth status.

The browser opened on another machine

Cancel the attempt and run foxcut auth login --manual.

A generation command returned a job instead of media

That is expected. FoxCut generations are asynchronous; use foxcut generation get JOB_ID until the job reaches a terminal state.

The account has insufficient credits

Run foxcut account status, then use estimate_generation_cost before retrying with a smaller batch, shorter duration, or different quality setting.

A model or preset name is rejected

The live catalog can change. Run foxcut models list, foxcut presets list, or foxcut tools list before constructing a job.

Links

• FoxCut CLI
• CLI documentation
• FoxCut MCP
• GitHub repository
• Support
• Privacy
• Terms

License

Copyright FoxCut. All rights reserved. See the repository and FoxCut Terms for applicable usage rights.