CLI

The fusedframes command finds and reads the documents FusedFrames makes from your recorded work. It suits both audiences: run it in a terminal and it prints something you can read, pipe it anywhere and it prints JSON that scripts and AI coding agents like Claude Code and Cursor can parse. It is read-only. It cannot record anything and it cannot create, change or delete anything. Recording stays in the desktop app.

#Install

npm install -g @fusedframes/cli

The npm package needs Node.js 20 or later. If you would rather not use Node, standalone binaries for macOS, Linux and Windows are on GitHub Releases with a SHA256SUMS file to check your download against.

#Set your API key

The CLI needs an API key; see Authentication to create one and to understand what a key can see. Pipe the key in on standard input:

echo "ff_your_key" | fusedframes config set-key

Keys typed on the command line leak into your shell history, so the CLI only reads keys from stdin and refuses one passed as an argument. In an interactive terminal, fusedframes config set-key on its own prompts for the key with hidden input.

The key must look like a key: ff_ followed by 64 hex characters. A partial paste is refused on the spot rather than saved and left to fail later on an unrelated command.

• fusedframes whoami checks the key works and lists every library it can read. Run it first when something is not returning what you expect.
• fusedframes config show prints your settings with the key masked.
• The FUSEDFRAMES_API_KEY environment variable overrides the saved key.
• fusedframes logout removes the saved key from your computer.

#Commands

search and documents list filter with --category, --tag and --app; search also takes --library <id> to stay inside one library. search, documents list and documents source-recordings page their results with --page and --page-size (page 1 and 20 results per page by default).

#Output

The format follows where the output is going.

• Piped, redirected or captured (a script, an agent, | jq, > file): one line of compact JSON, the API response passed through unchanged. This is the contract to build on.
• Straight to a terminal: the same response rendered to read, with aligned tables and a document's steps laid out under its own section headings.

--json forces the machine format anywhere, which is what you want when checking by hand what a script will receive.

fusedframes libraries list          # a table, when you are at a terminal
fusedframes libraries list --json   # one line of JSON, always
fusedframes libraries list | jq     # JSON, because it is piped

#Examples

Search every library you can see, filtered to one application:

fusedframes search "failed deployment" --app Terminal | jq

A trimmed response:

{
  "documents": [
    {
      "id": "doc_01h...",
      "title": "Roll back a failed deployment",
      "category": "Deploys",
      "relevance": { "score": 0.91, "semanticSimilarity": 0.88 }
    }
  ],
  "total": 1,
  "matchedTotal": 1,
  "lowConfidence": false
}

Read the full document behind a hit, with its edges included:

fusedframes documents get doc_01h...

Follow the document's outgoing edges two steps to see what usually comes next:

fusedframes traverse doc_01h... --direction outgoing --label "often next" --depth 2

Errors follow the same rule: the JSON shape {"error":{"code":"...","message":"..."}} on stdout for anything parsing it, a plain message on stderr for a person. The exit code is 1 for any error. A typical agent run chains the read commands: search, then documents get, then traverse, then documents source-recordings for the real examples behind a document.

#Tab completion

fusedframes completions zsh > ~/.zsh/completions/_fusedframes
fusedframes completions bash > /etc/bash_completion.d/fusedframes
fusedframes completions fish > ~/.config/fish/completions/fusedframes.fish