CLI Reference

CLI Reference

Installing Noema adds a noema command.

noema --help
noema <command> --help

Command	Purpose
noema compress	Compress text and print the notation
noema build-graph	Ingest text files into a .noema bundle
noema query	Retrieve context for a question from a bundle
noema inspect	Show statistics for a bundle
noema benchmark	Compare retrieval tokens with a full-document baseline

noema compress

noema compress "Larry Page founded Google in 1998."
noema compress --file article.txt

Option	Meaning
TEXT	Text to compress. Omit it and use --file instead
--file, -f	Read text from a file
--spacy-model	spaCy pipeline, default en_core_web_sm

Prints the notation, then original tokens, notation tokens, percent saved and confidence. If you pass both TEXT and --file, the file wins. If you pass neither, the command fails with "Provide TEXT or --file PATH".

noema build-graph

noema build-graph docs/a.txt docs/b.txt --output company_kb.noema

Option	Meaning
DOCUMENTS...	One or more UTF-8 text files. Each file is one document
--output, -o	Where to save the bundle. Required
--batch-size	Documents canonicalized together, default 100
--spacy-model	spaCy pipeline
--embedding-model	sentence-transformers model, default all-MiniLM-L6-v2

Shows a progress bar while ingesting, then prints the entity and relation counts. The shell expands wildcards such as docs/*.txt. Windows cmd and PowerShell do not, so list the files or use a different shell.

noema query

noema query company_kb.noema "Who is Google's CEO?" --max-tokens 200

Option	Meaning
BUNDLE	A .noema file
QUESTION	The question to retrieve context for
--top-k	Vector search hits, default 5
--hops	Graph expansion distance, default 1
--max-tokens	Token budget, default 200
--format	notation (default) or natural_language

Prints the context and a token count, noting when --max-tokens truncated it. See Retrieval.

noema inspect

noema inspect company_kb.noema

Reads the bundle's manifest and prints schema version, creation time, spaCy and embedding model names, counts of entities, relations, events, indexed facts and source documents, and the file size.

noema benchmark

Compares what retrieve() returns with stuffing the whole source text into the prompt, for your own bundle and questions.

noema benchmark company_kb.noema -d docs/a.txt -d docs/b.txt -q "Who is Google's CEO?" -q "Who founded Google?"

Option	Meaning
BUNDLE	A .noema file
--document, -d	A source document for the baseline. Repeat for more. Required
--query, -q	A question to run. Repeat for more. Required
--top-k, --hops, --max-tokens	Retrieval settings, as in query

Prints retrieved tokens, baseline tokens and the reduction for each question, plus the average. This measures token cost only. It does not check whether the retrieved context contains the answer. For accuracy comparisons, see Benchmarks.