Skip to content

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:

  1. Install — get the fune binary onto your machine.
  2. Commands — everything the CLI can do.
  3. Fluid contract — the HTTP API the CLI is built on.

Install the latest release with a single command:

Terminal window
curl -fsSL https://fune-cli-prod.fune.fm/releases/cli/install.sh | bash

The 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/bin on Apple Silicon, /usr/local/bin on Intel), then /usr/local/bin — whichever is on your PATH and 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:

Terminal window
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.

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.

Before you can submit or list tracks, authenticate once:

Terminal window
fune login

This 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.

fune [COMMAND] [ARGS] [--json]
CommandDescription
fune loginAuthenticate via the browser (stores a token in ~/.fune/credentials.json).
fune logoutRemove the stored credentials.
fune helpShow all available commands (native + fluid module commands).
fune track listList 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.
  • --json — print machine-readable JSON. Without it, output is a human-readable YAML-like format. Works on any of the track commands.
Terminal window
fune track list
fune track list --json

Returns every track on your account.

Terminal window
fune track status 019eedc6-2f9b-7e10-8508-8867636bca9d

Shows 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.

Submit exactly one source — either a local file or a URL (the two flags are mutually exclusive):

Terminal window
# Upload a local file
fune track submit --file ./book.epub
# Submit a URL to save
fune track submit --url https://example.com/article

Both forms print the new track’s upload_id and track_id on success.

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.

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.

Terminal window
# GET /api/tracks
fune track list --json