fused-cli

Fused CLI

Session start

Before any task that requires the CLI or authentication, run fused whoami to confirm the CLI is available and authenticated. If the command is not found:

uv tool install 'fused[vector]' --upgrade  # permanently installs (or repairs) fused on PATH
fused claude plugin add                     # re-registers the Claude plugin

Then open a new Claude Code session. This is the complete reinstall — no other context is needed.

Finding the CLI

fused is installed as part of the fused Python package. The CLI ships in fused>=2, which requires Python 3.10 or newer — on Python 3.9 pip install fused falls back to a 1.x release that has no fused entry point. If fused is not on PATH, locate or install it before running any commands:

1. Check PATH first: which fused — if found, use it directly.
2. Not found? Install permanently (recommended): uv tool install 'fused[vector]' — installs fused as a persistent tool so it is always on PATH, even in new sessions. The vector extra bundles geopandas/pandas/shapely so local fused run works (without it, deserializing a result DataFrame raises ModuleNotFoundError: No module named 'pandas'). Requires uv (install instructions).
3. Quick one-off (no permanent install): uvx fused — runs the latest version without touching PATH. Use this only when you don't need fused to persist across sessions.
4. Project venv: if the project uses a .venv, run uv run fused or .venv/bin/fused. Confirm the venv is Python 3.10+ (.venv/bin/python --version); if it's 3.9, recreate it with uv venv --python 3.11 .venv before installing.
5. Conda env: the binary may live inside a conda environment (~/miniforge3/envs/<env>/bin/fused). Activate the env or call the full path. If the env is on Python 3.9, create a new one with conda create -n fused python=3.11.

Windows

On Windows the same rules apply, with a few differences:

• Check PATH: use where fused (not which) in cmd/PowerShell.
• Python Launcher: Windows ships a py launcher — use py --version to check the active version and py -3.11 -m pip install "fused[vector]>=2" to target a specific version.
• fused not found after pip install: the Scripts directory (%APPDATA%\Python\Python3XX\Scripts\ or %LocalAppData%\Programs\Python\Python3XX\Scripts\) is often not on PATH. Run python -m site --user-scripts to print the exact path, then add it to PATH (search "environment variables" in the Start menu → edit the Path user variable) and open a new terminal.
• Install uv on Windows (if not present):

  powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
  

  Restart the terminal after installing, then use uvx fused as usual.

Global flags

• --env TEXT (env: FUSED_ENV)
• --format [json|text] (env: FUSED_CLI_FORMAT) — set to json for machine-readable output

Top-level commands

fused canvas

Most canvas subcommands take a CANVAS_REF (name or ID) plus:

• --id — treat the ref as a canvas ID rather than a name
• --team (where supported) — treat the name as a team canvas name

• When pushing a canvas, prefer to test the canvas to make sure your changes work. For JSON UI nodes, you can run using fused json-ui run-inline-widget/fused json-ui run-shared-widget, for UDFs, you can run them using fused run.

Directory name ≠ canvas name. By default push uses the source directory's name as the canvas name. If your local folder is named differently from the remote canvas (e.g. folder is fused-canvas/, remote canvas is feedback_pipeline), the push will try to create a new canvas with the folder's name — and fail if that name contains hyphens. Always pass --canvas explicitly when the names differ:

# Push ./fused-canvas/ to the existing canvas named "feedback_pipeline"
fused canvas push ./fused-canvas --canvas feedback_pipeline

If you're unsure of the remote canvas name, run fused canvas list first.

Reading an existing canvas

To understand what a canvas contains, pull it locally first, then read the files:

fused canvas pull CANVAS_REF -o ./local_canvas

Once pulled, the output directory contains:

• canvas.toml — nodes, edges, viewport (see the fused:canvas-toml skill for the full format)
• *.py / *.json / *.md / *.html — one source file per UDF node

To inspect a single UDF's parameters without pulling the full canvas, use fused udf-schema CANVAS UDF.

Anti-patterns

fused files

fused secrets

User secrets are read-only — --user is only valid on get and list.

fused integrations

OAuth-style connectors for third-party services. Each provider exposes the same three subcommands (connect, token, revoke); Snowflake's connect takes extra flags because it uses customer-owned OAuth clients.

Providers: airtable, google-drive (alias gdrive), hubspot, notion, snowflake.

fused json-ui

Inspect, validate, and render JSON-UI widget component schemas (the same schemas covered by the fused:json-ui-schemas skill). Use these subcommands as your primary debugging tools when authoring or editing widget_*.json files — they're faster than round-tripping through the canvas UI.

Debugging flow: edit the widget JSON → fused json-ui validate <file> → push → fused json-ui run-shared-widget <share-token> <widget-name> --screenshot-filename out.png to confirm it renders. Use run-inline-widget when iterating on a widget that hasn't been committed yet.

fused claude

Manage Fused for Claude Code via the claude CLI.

First-time install: uv tool install 'fused[vector]' then fused claude plugin add — this permanently installs fused on PATH so Claude can find it in every future session. After opening a new Claude Code session, verify with fused whoami.

If fused is not found in a new session: run uv tool install 'fused[vector]' (no other context needed) then fused claude plugin add, and open a new session.

fused completion

Calling UDFs: HTTP vs fused run

Use this to decide which approach to suggest:

Default to fused run during development. Only suggest HTTP when the goal is an external caller or a production integration that runs without Fused credentials. Never suggest an HTTP call on a canvas that hasn't been shared — it will return 404 or 403.

Calling UDFs via HTTP

Every shared canvas exposes a public HTTP API — no Fused SDK or credentials required on the caller side. This is the foundation for building bots, external integrations, and any service that calls Fused from outside Python.

HTTP API URL format

Once the canvas is public, each UDF is callable as:

GET https://udf.ai/<share_token>/<udf_name>?param1=value1&param2=value2&format=json

• format=json returns a JSON array of row objects (one per DataFrame row). Omitting it returns a binary format.
• Parameters are passed as query string values — strings, integers, and booleans all work.

Example:

curl "https://udf.ai/fc_abc123/ask_question?question=what+is+fused&format=json"
# → [{"answer": "Fused is a platform for running Python in the cloud..."}]

Discover available UDFs

The .api.json endpoint returns an OpenAPI spec listing all UDFs in the canvas and their parameters:

curl "https://udf.ai/<share_token>.api.json"

Use this to build tool lists for LLM agents — the summary field in each path is the UDF's docstring, which the canvas bot uses as the tool description.

---

fused run CANVAS UDF

Runs a UDF and prints the result. The UDF argument is passed to fused.load, which accepts:

• Fused identifier: user@example.com/my_udf or my_udf (resolved against CANVAS as the collection)
• Local Python file: udf.py or any .py path
• GitHub tree/blob URL: https://github.com/org/repo/tree/... or .../blob/...
• Inline UDF source: a string containing at least one newline is treated as Python module text

Options:

• --engine [remote|local]
• --instance-type TEXT — remote instance type override
• --max-retry INTEGER
• --cache-max-age TEXT — e.g. 10s, 5m, 1h
• --cache / --no-cache
• --disk-size-gb INTEGER
• --stdin — read UDF source from stdin instead of passing UDF (do not pass UDF with --stdin)
• --verbose / --no-verbose — show UDF stdout/stderr (default on)

fused[vector] required for local result deserialization. When running via uv run, the result DataFrame is deserialized locally and requires pandas to be available in that environment. Without it you get ModuleNotFoundError: No module named 'pandas' even if the UDF itself doesn't use pandas. Install fused[vector] — it pulls in geopandas (and therefore pandas), plus shapely, which most UDFs need:

uv run --no-project --with 'fused[vector]' fused run my_canvas my_udf --param=value

--no-project avoids pulling in the current directory's dependencies, which can conflict with fused's requirements. If you only need plain pandas and not the geospatial stack, --with fused --with pandas also works.

Additionally, fused run accepts arbitrary keyword args matching the UDF's signature, e.g. --abc=123 is forwarded as the abc parameter to the UDF. These pass-through args are not listed in --help.

When running locally via uv run, install fused[vector] if the UDF returns a DataFrame — the CLI needs pandas to deserialize the result, and the error (ModuleNotFoundError: No module named 'pandas') appears at result-read time, not inside the UDF itself. fused[vector] bundles pandas (via geopandas) along with shapely, covering both plain and geospatial DataFrames:

uv run --with 'fused[vector]' fused run my_canvas my_udf --param=value

fused udf-schema CANVAS UDF

Prints a UDF's API schema (parameter types, return shape) without executing it. The UDF argument is passed to fused.load and accepts the same forms as fused run:

• Fused identifier: user@example.com/my_udf or my_udf (resolved against CANVAS as the collection)
• Local Python file: udf.py or any .py path
• GitHub tree/blob URL
• Inline UDF source (a string containing at least one newline is treated as Python module text)

Options:

• --stdin — read UDF source from stdin instead of passing UDF (do not pass UDF with --stdin)

Use this to introspect parameters before calling fused run with --<param>=<value> kwargs, or to confirm a UDF's signature matches what a widget or downstream UDF expects.

Tips

• If the CLI lives in a project venv, prefix with uv run so the right environment is used.
• For machine-readable output in scripts, pass --format json.
• Run fused <command> --help to confirm flags before scripting — this reference may lag the CLI.
• When appropriate, give the user the URL to the created canvas so they can open it in their browser and see the result.
• Prefer the CLI for debugging. Before asking the user to open the canvas UI to check a change, try to reproduce locally: fused run for UDFs, fused json-ui validate / run-shared-widget for widgets, fused canvas pull --dry-run to inspect what changed remotely. This catches most issues without a round trip.