Query behavioural patterns captured by FusedFrames from the command line. Designed for AI agents to traverse pattern libraries, follow relationships between patterns and retrieve evidence.
No installation required. Run directly with npx:
npx @fusedframes/cli --helpOr install globally:
npm install -g @fusedframes/cliCreate an API key in your FusedFrames team settings under Integrations > API keys, then configure the CLI:
echo "ff_your_api_key" | fusedframes config set-keyThe key is stored at ~/.config/fusedframes/config.json with restricted file permissions.
You can also set the key via environment variable:
export FUSEDFRAMES_API_KEY=ff_your_api_keyVerify your configuration:
fusedframes config showList all pattern libraries your API key has access to:
fusedframes libraries listGet detail for a specific library:
fusedframes libraries get <library-id>Discover the vocabulary of a library:
fusedframes libraries categories <library-id>
fusedframes libraries tags <library-id>
fusedframes libraries applications <library-id>List patterns in a library with optional filters:
fusedframes patterns list <library-id>
fusedframes patterns list <library-id> --category "Deployment"
fusedframes patterns list <library-id> --tag "rollback" --app "Terminal"
fusedframes patterns list <library-id> --search "failed health check"Get full detail for a pattern, including its relationships:
fusedframes patterns get <pattern-id>This returns the pattern's behaviour, reasoning, trigger, outcome, category, tags, standard operating procedure steps, and all incoming and outgoing edges to other patterns.
Get the evidence actions that support a pattern:
fusedframes patterns evidence <pattern-id>Each evidence action includes the original question, response, and a formatted event timeline showing exactly what happened.
Get the full pattern graph for a library in a single call:
fusedframes graph <library-id>Returns all patterns and all edges. Useful for building a complete picture of a library.
Follow relationships from a specific pattern:
fusedframes traverse <pattern-id>
fusedframes traverse <pattern-id> --depth 2
fusedframes traverse <pattern-id> --direction outgoing --label "often next"
fusedframes traverse <pattern-id> --depth 3 --direction bothDepth controls how many levels of connected patterns to follow (1-3). Direction can be outgoing, incoming, or both.
Edge labels describe the relationship between patterns:
| Label | Meaning |
|---|---|
often next |
What typically happens after |
often previous |
What typically happens before |
variation to |
An alternative approach |
contradicts |
Conflicts with this pattern |
often occurs with |
Usually happening alongside |
exception to |
Edge case where a pattern doesn't apply |
Search across all accessible libraries:
fusedframes search "failed deployment"
fusedframes search "onboarding" --category "HR"
fusedframes search "review" --library <library-id>Commands that return lists support --page and --page-size:
fusedframes patterns list <library-id> --page 2 --page-size 50
fusedframes patterns evidence <pattern-id> --page 1 --page-size 10Defaults: page 1, 20 results per page.
All commands output JSON to stdout. Errors are also JSON:
{ "error": { "code": "unauthorised", "message": "Invalid or missing API key" } }Exit codes: 0 for success, 1 for errors, 2 for invalid arguments.
| Variable | Purpose |
|---|---|
FUSEDFRAMES_API_KEY |
API key. Overrides the saved config. |
FUSEDFRAMES_API_URL |
API base URL. Defaults to https://api.fusedframes.com. |
The CLI stores its configuration at ~/.config/fusedframes/config.json. The directory is created with 700 permissions and the file with 600 permissions.
Environment variables take precedence over the config file.
This CLI is designed to be called by AI agents (Claude Code, Cursor, Windsurf, Codex) via shell commands. Each command returns structured JSON that the agent can parse and act on.
A typical agent workflow:
fusedframes search "deployment failure"to find relevant patternsfusedframes patterns get <id>to read the full pattern and its edgesfusedframes traverse <id> --depth 2to explore related patternsfusedframes patterns evidence <id>to see the raw actions that support the pattern
The agent uses pattern edges to navigate between related behaviours and build context about how your team works.
- Node.js 18 or later
- A FusedFrames account with a Pro or Enterprise plan
- An API key created in your team's integration settings