WidemileDocs
ToolsWorkflowsChangelogGitHub
  • Introduction
  • Getting started
  • CLI (wm)
  • Configuration
  • Tool index
CLI

wm — the Widemile command-line client

The fastest way to use Widemile from a terminal, a Makefile, or any CI job. One npm install, one login, and you're generating.

No infrastructure, ever
wm is a thin client over our hosted REST API. There is nothing to deploy, no server to spin up, no MCP connector to configure. If you already use Claude with the Widemile connector, this is the same backend — just driven from your shell.

1 · Install

npm i -g @wmstudio/cli

Verify the install:

bash
wm --version

2 · Log in

Personal access token creation from the dashboard is temporarily unavailable. Existing tokens can still be used with:

bash
wm login

The token is saved to ~/.wm/config.json (file mode 0600, directory mode 0700). You stay logged in forever; refresh by re-running wm login whenever you rotate the key.

CI / scripts
Set WM_API_KEY in your environment — it overrides the config file and lets you skip wm login entirely.

3 · First call

The fastest proof everything works:

bash
wm whoami
# → tester@wmstudio.io · 1234 credits · plan pro

wm gen image "a single red apple on white seamless" -o apple.png
# → https://v3b.fal.media/files/.../apple.png  (also saved to ./apple.png)

Everyday commands

bash
# Generate an image
wm gen image "minimalist espresso machine, soft daylight" --aspect-ratio 4:3 -o hero.png

# Image-to-image refinement
wm gen image "same machine, golden hour rooftop" --image-url ./hero.png -o hero-v2.png

# Image-to-video (polls until done)
wm gen video "slow dolly-in, golden hour reflection" --image ./hero.png --duration 5 -o ad.mp4

# Check what's running
wm jobs list --status running
wm jobs get <jobId>

Cost confirmation

Every generation command (gen image, gen video) shows the estimated credit cost and asks you to confirm before charging. After the generation completes you also see how many credits you have left.

bash
$ wm gen image "red apple on white"
? Image generation · vertex-ai/gemini-3-pro-image
  Estimated cost: 18 credits (~$0.300)
  Proceed? (Y/n) y
✔ Image ready.
› 18 credits charged · 11014701 credits remaining

Skip the prompt with -y/--yes for unattended/CI use, or pass --json (which auto-skips and emits machine-readable output):

bash
wm gen image "red apple" --yes -o apple.png
wm --json gen image "red apple" | jq -r .imageUrl

Defaults are tuned for current best-in-class quality:

  • gen image (text-to-image) → vertex-ai/gemini-3-pro-image
  • gen image --image-url ... → vertex-ai/gemini-3-pro-image (auto-picked)
  • gen video → bytedance/seedance-2.0-fast

Override any default with -m/--model <id>.

Full brand campaign in one command

The campaign subcommand submits a brief to the director_* pipeline (script → storyboard → image gen → video gen → master cut) and follows the run(s) to completion.

bash
# Single 60s video from a brief
wm campaign "Premium oat milk launch, Scandinavian minimal, slow pacing" \
  --duration 60 --platform youtube --style cinematic

# 3 parallel variations
wm campaign "Premium espresso campaign, modernist still lifes" \
  --variations 3 --project-id <your-project-id>

Web search

The search subcommand runs a Tavily-powered web search through the same backend Deep Agents use internally. Each call costs 1 credit (basic) or 2 credits (advanced) and is charged only on success.

bash
# Quick search
wm search "next.js 16 release notes"

# Deep dive, last week only, 10 results
wm search "OpenAI o3 benchmarks" --depth advanced --time week --max 10

# Restrict to specific sources
wm search "vector databases comparison" \
  --include-domain wikipedia.org \
  --include-domain github.com

# Pipe results into jq
wm --json search "latest TypeScript release" | jq -r '.results[].url'

Auth precedence

When multiple credentials are present, wm picks them in this order (highest first). This is identical to the rule used by mcp-director, so behaviour is predictable across surfaces.

  1. --api-key flag
  2. WM_API_KEY environment variable
  3. ~/.wm/config.json (written by wm login)
  4. None → exits with auth_required (code 10) and a hint to run wm login.

Scripting — --json mode

Every command supports --json for machine consumption. Stderr stays human-readable; stdout becomes a single JSON object that you can pipe into jq.

bash
wm --json gen image "a red apple" | jq -r .imageUrl
# → https://v3b.fal.media/files/.../apple.png

wm --json whoami | jq .creditsRemaining
# → 1234

For structured logs (suitable for log aggregators) set WM_LOG_FORMAT=json — the schema matches what mcp-director emits.

Exit codes

Stable contract — use them in shell scripts and CI gates. See also errors reference.

text
0    OK
2    Usage error          (bad arguments / unknown command)
10   auth_required        (run `wm login` or set WM_API_KEY)
11   auth_invalid         (server rejected the token)
20   asset_url_required   (URL missing or unreachable — upload first)
30   upgrade_required     (insufficient credits — top up to continue)
31   rate_limited
40   network              (DNS / TLS / connect failure)
50   server               (5xx from API)
51   timeout
99   unexpected           (uncategorised crash)

Uninstall

bash
npm uninstall -g @wmstudio/cli
rm -rf ~/.wm     # removes the saved API key and any local state

Source on GitHub: PrincipeRosso/wm-cli. Report bugs and request features there.

On this page
  • 1 · Install
  • 2 · Log in
  • 3 · First call
  • Everyday commands
  • Cost confirmation
  • Full brand campaign in one command
  • Web search
  • Auth precedence
  • Scripting · --json mode
  • Exit codes
  • Uninstall
Widemile MCP — v2.0.0
Docs home