Skip to content

Command line

Installing the package adds the spectrafuse command.

spectrafuse [--version] [-v] <command> ...
Global option Meaning
--version print the version and exit
-v, --verbose print one timed line per pipeline step (to stderr)

Every command takes --index FOLDER. All commands except info take --set KEY=VALUE (repeatable) to change any setting. Values are read as JSON, and anything that is not valid JSON is taken as text:

--set chunk_tokens=512 --set embedder=ollama --set n_clusters=null
--set 'edge_weights={"semantic": 0.5, "entity": 0.5}'

On an error raised by SpectraFuse (a bad setting, a missing index), the command prints spectrafuse: error: <message> and exits with status 1.

spectrafuse ingest

Build an index from a file or a folder (.txt, .md, .pdf; folders are searched recursively). Prints the ingestion summary as JSON.

spectrafuse ingest PATH --index FOLDER [--set KEY=VALUE ...]
spectrafuse ingest docs/ --index my_index --set embedder=ollama --set chunk_tokens=512

Print the selected chunks (rank, document, score, tokens, reason), then the context.

spectrafuse search QUESTION --index FOLDER [--budget N] [--json] [--set KEY=VALUE ...]
spectrafuse search "Where is Helios Energy based?" --index my_index --budget 2000
Option Meaning
--budget N token budget (default: the token_budget setting, 12,000)
--json print question, tokens, chunks and context as JSON

spectrafuse answer

Search, then answer with a local Ollama model. Prints the answer and the source documents.

spectrafuse answer QUESTION --index FOLDER [--budget N] [--model NAME] [--set KEY=VALUE ...]
spectrafuse answer "Where is Helios Energy based?" --index my_index --model gemma3:4b
Option Meaning
--budget N token budget
--model NAME the Ollama model (default gemma3:4b)

For other LLMs, use answer() in Python.

spectrafuse graph

Write the interactive graph view.

spectrafuse graph --index FOLDER [--out FILE] [--question TEXT] [--max-nodes N] [--set KEY=VALUE ...]
spectrafuse graph --index my_index --out graph.html --question "Where is Helios Energy based?"
Option Meaning
--out FILE the HTML file to write (default graph.html)
--question TEXT highlight this question's retrieval path
--max-nodes N the most chunks to draw (default 1,500)

spectrafuse info

Print what an index contains (its info.json): documents, chunks, edges per signal, the weights used, the backend and the version that built it.

spectrafuse info --index my_index

From Python

The command is also available as a function, which returns the exit status:

from spectrafuse.cli import main
main(["search", "Where is Helios Energy based?", "--index", "my_index", "--json"])