fune CLI
The fune CLI lets you submit tracks to fune and check their status from your
terminal. It ships as a small native host binary (fune) that authenticates you
and then runs the fluid WASM module, which implements the commands and talks
to the fune API.
This page covers three things:
- Install — get the
funebinary onto your machine. - Commands — everything the CLI can do.
- Fluid contract — the HTTP API the CLI is built on.
Install
Section titled “Install”Install the latest release with a single command:
curl -fsSL https://fune-cli-prod.fune.fm/releases/cli/install.sh | bashThe script detects your platform, downloads the matching release from fune’s CDN,
and installs the fune binary.
Where it installs: the installer picks the first directory that’s already on
your PATH and writable without sudo, so fune just works after install:
- Run as root →
/usr/local/bin/fune. - Otherwise the Homebrew bin (
/opt/homebrew/binon Apple Silicon,/usr/local/binon Intel), then/usr/local/bin— whichever is on yourPATHand writable. - Fallback →
~/.local/bin/fune.
Set FUNE_INSTALL_DIR to force a specific directory. If it falls back to
~/.local/bin and that directory isn’t on your PATH, the installer prints the
line to add to your shell profile:
export PATH="${HOME}/.local/bin:${PATH}"On macOS the installer also clears the quarantine attribute so Gatekeeper won’t
block the binary, then verifies the install by running fune --version.
Fluid contract
Section titled “Fluid contract”The API backing this CLI is not stable and not guaranteed to evolve to be backwards-compatible. This means that any time, it might break your CLI version by:
- dropping entire endpoints
- requiring more parameters in a POST requests
- removing attributes from responses
- and many more failure modes
Whenever the API changes, we’ll release a new version of this CLI and yours will auto-update.
In practice, that means that:
- You should not write fix scripts that use the current CLI commands
- You should not reverse-engineer the underlying API to do your own HTTP requests
Instead, the fune CLI is only meant to be used by LLM agents that can adapt to
changes and decide how to use the version of fune they find themselves with.
Commands
Section titled “Commands”First run: log in
Section titled “First run: log in”Before you can submit or list tracks, authenticate once:
fune loginThis opens your browser to complete an OAuth flow. On success the session token
is written to ~/.fune/credentials.json with 0600 (owner-only) permissions —
the same file-based approach Heroku, the AWS CLI, and gcloud use. The login
server listens locally for up to 5 minutes; if the browser doesn’t open, the
command prints a URL you can visit manually.
Other commands
Section titled “Other commands”fune [COMMAND] [ARGS] [--json]| Command | Description |
|---|---|
fune login | Authenticate via the browser (stores a token in ~/.fune/credentials.json). |
fune logout | Remove the stored credentials. |
fune help | Show all available commands (native + fluid module commands). |
fune track list | List all your tracks. |
fune track status <ID> | Show the status of a single track. |
fune track submit --file <PATH> | Submit a local file (PDF, EPUB, HTML, …). |
fune track submit --url <URL> | Submit a URL to be saved. |
Global flag
Section titled “Global flag”--json— print machine-readable JSON. Without it, output is a human-readable YAML-like format. Works on any of thetrackcommands.
fune track list
Section titled “fune track list”fune track listfune track list --jsonReturns every track on your account.
fune track status <ID>
Section titled “fune track status <ID>”fune track status 019eedc6-2f9b-7e10-8508-8867636bca9dShows the status of one track by its ID (a UUID, as returned by
fune track list). Reports an error if the track doesn’t exist.
fune track submit
Section titled “fune track submit”Submit exactly one source — either a local file or a URL (the two flags are mutually exclusive):
# Upload a local filefune track submit --file ./book.epub
# Submit a URL to savefune track submit --url https://example.com/articleBoth forms print the new track’s upload_id and track_id on success.
The Track object
Section titled “The Track object”fune track list and fune track status return tracks with this shape:
{ "id": "019eedc6-2f9b-7e10-8508-8867636bca9d", "last_seq": 4, "blob": { "title": "Some title", "status": "ready", "cover_url": "https://…", "source_url": "https://…", "archived": false }, "created_at": "2026-06-22T05:20:49Z", "updated_at": "2026-06-22T05:23:10Z"}cover_url and source_url may be null. The mutable fields live under blob;
last_seq is the track’s current sync watermark.
Examples
Section titled “Examples”Each endpoint maps to a CLI command. The CLI handles auth (the token from
fune login) and request shaping for you; add --json to get the raw API
response.
# GET /api/tracksfune track list --json# GET /api/tracks/{track_id}fune track status 019eedc6-2f9b-7e10-8508-8867636bca9d --json# POST /api/tracks (multipart)fune track submit --file ./book.epub --json# POST /api/tracks (multipart)fune track submit --url https://example.com/article --json