VIX CLI

Command-line access to VIX media operations.

Install

npm install -g @soberbunnylabs/vix-cli
vix version

One-off use:

npx @soberbunnylabs/vix-cli version

Sign In

vix auth login
vix account status
vix doctor

vix auth login opens a browser sign-in and stores a local token for the CLI. vix doctor checks the local Node.js runtime, auth, and operation search.

Lessons

Method guides for agents, shipped inside the CLI:

vix learn                    # list lessons
vix learn composition        # the decompose-backward method
vix learn error-recovery     # blocked or failed runs

Common Flows

Remove an image background:

vix recipes run remove-background --image ./input.png --out ./result.png

Generate an image:

vix recipes run generate-image "a glass cube on a white background" \
  --out ./result.png

Plan before running an explicit operation:

vix operations plan vix.image.remove_background \
  --image ./input.png \
  --output-name cutout.png \
  --json

Run an explicit operation:

vix runs create vix.image.remove_background \
  --image ./input.png \
  --output-name cutout.png \
  --wait \
  --out ./result.png

Handles

VIX commands use three reusable handles:

• operationId
• mediaFileId
• executionId

Upload once, reuse the returned mediaFileId:

vix media upload ./input.png
vix runs create vix.image.remove_background --image media_... --wait

Find recent CLI and MCP runs:

vix runs list --origin all --json
vix runs get exec_... --json
vix runs wait exec_... --out ./result.png

Output

Plain output is compact for shell use. For example, vix media upload ./input.png prints only the mediaFileId, and successful wait commands print the output path, URL, or first output handle.

Use --json when an agent needs the full response:

vix operations search "remove background" --limit 3 --json
vix account status --json
vix recipes list --json

operations search shows operations that are enabled for the installed CLI.

Use --jsonl for newline-delimited run lifecycle events. Waits emit waiting or submitted, progress, optional retry, and exactly one terminal final or error event. Stdout contains JSON lines only:

vix runs wait exec_... --jsonl
vix runs create <operationId> --inputs - --wait --jsonl < inputs.json
vix recipes run generate-image "a glass cube" --jsonl

A failed or cancelled run emits a final event with ok: false, its terminal status, and the command exit code. Usage, auth, transport, and timeout failures emit an error event.

Use --quiet on wait commands to hide progress while keeping the final output:

vix runs wait exec_... --quiet --out ./result.png

Inputs

Use typed media flags for common handles:

vix operations plan vix.image.remove_background --image ./input.png --json
vix runs create <operationId> --video ./clip.mp4 --wait
vix runs create <operationId> --audio ./track.wav --wait

Prefer the named flags shown by vix operations get:

vix runs create vix.image.generate.flux_2_klein_4b \
  --prompt "a studio product photo" \
  --aspect-ratio "1:1" \
  --wait \
  --out ./result.png

Use --input flag-name=value only as a generic fallback when a public CLI flag is easier to pass that way.

Use an inputs file when that is easier for an agent to prepare:

vix operations plan vix.image.generate.flux_2_klein_4b \
  --inputs ./inputs.json \
  --json

Pass - to read the JSON object from stdin without creating a temporary file:

printf '{"prompt":"a studio product photo","aspect-ratio":"1:1"}' |
  vix runs create vix.image.generate.flux_2_klein_4b --inputs - --wait --jsonl

Name the asset created by a run without changing its output handle or URL:

vix runs create <operationId> --output-name campaign-hero.png --wait
vix runs create <operationId> \
  --output-name image=campaign-hero.png \
  --output-name mask=campaign-mask.png \
  --wait

The bare form is accepted only when the operation has exactly one file output. Use handle=file mappings for multi-output operations, and pass the same flags to vix operations plan before spending.

Agent Harness Integrations

Print the current install and OAuth routes without changing harness config:

vix integrations
vix integrations get codex
vix integrations get claude-code --json
vix integrations get chatgpt --json
vix integrations get cursor --jsonl

The four routes share the hosted MCP endpoint and expose only public install, settings, deep-link, and OAuth instructions.

For ChatGPT, enable Developer mode under Settings → Security and login, then open Settings → Plugins, select +, and enter https://mcp.vixsbl.com/mcp.

Codex plugin install:

codex plugin marketplace add soberbunnylabs/vix-skills
codex plugin add vix@vix

Direct Codex MCP fallback:

codex mcp add vix --url https://mcp.vixsbl.com/mcp
codex mcp login vix

Claude Code plugin install:

claude plugin marketplace add soberbunnylabs/vix-skills
claude plugin install vix@vix

Authenticate from the shell with claude mcp login vix; the interactive /mcp screen remains available as a UI fallback.

Remote MCP

Remote MCP endpoint:

https://mcp.vixsbl.com/mcp

Use the CLI for shell commands, local files, and explicit run handles. Use the remote MCP endpoint when your MCP host supports it.

Agent Skills

Teach your agent when and how to reach for VIX — one command installs the VIX skill into 70+ harnesses:

npx skills add soberbunnylabs/vix-skills

Plugins, per-harness setup, and everything else: github.com/soberbunnylabs/vix-skills.