Thalabus CLI Reference

Overview

The Thalabus CLI (python -m src.cli.thalabus) provides a command-line interface for managing ontologies, categories, documents, dossiers, templates, reasoning documents, hints, and knowledge base configurations. It's composed of modular resource-specific handlers in PythonServer/src/cli/.

General Usage

python -m src.cli.thalabus <resource> <action> [options]

Global Options

• --debug: Enable debug-level console logging
• --llm-out: Include LLM output messages in logs (excluded by default)
• -v, --verbose: Show more details
• -w, --write: Write output to .md in output/ and open in VS Code
• -wc, --write-clear: Remove previous .md files from output before writing

---

user

Create users and their hidden ACL user groups.

python -m src.cli.thalabus user create USERNAME [--name FULLNAME] [--email EMAIL]

USERNAME is stored as User.username. User.id is generated as a GUID and is not the same value as the username. The command is idempotent and ensures the user's isUserGroup=true group and MEMBER_OF relationship exist.

To delete a user by either username or GUID:

python -m src.cli.thalabus user delete USERNAME_OR_ID

Examples:

python -m src.cli.thalabus user create test-user-1 --name "Test User 1"
python -m src.cli.thalabus user create test-user-2 --name "Test User 2"
python -m src.cli.thalabus user create test-user-3 --name "Test User 3"

---

Resources and Commands

ontology

Manage ontologies (classification schema).

Commands

ls — List all ontologies

python -m src.cli.thalabus ontology ls [-v] [-w] [-wc]

Lists all available ontologies in the system with entity/relationship counts.

find-dup-categories — Find duplicated Category nodes

python -m src.cli.thalabus ontology find-dup-categories [-v] [-w] [-wc] [-d DOCUMENT_IDS...]

Identifies duplicate Category nodes for documents. Can restrict search to specific documents.

export — Export ontology schema to OWL or JSON-LD

python -m src.cli.thalabus ontology export --format <owl|ttl|jsonld> [-o ONTOLOGY_ID] [--out FILEPATH] [--syntax <xml|turtle>]

Exports the ontology schema (entity types, relationship types, attributes, sources, and keyword categories) to a file. When -o is omitted, all ontologies are exported together.

Option	Description	Default
--format	Output format: owl (RDF/XML), ttl (Turtle), jsonld	jsonld
-o, --ontology	Ontology ID to export (omit to export all)	all
--out	Output file path	output/<ONTOLOGY_ID>_export.<ext>
--syntax	RDF serialization for OWL: xml or turtle (ignored for jsonld)	xml

Examples:

# Export FictionalStories ontology to JSON-LD
python -m src.cli.thalabus ontology export --format jsonld -o FictionalStories

# Export EAM ontology to OWL/RDF-XML
python -m src.cli.thalabus ontology export --format owl -o EAM

# Export EAM ontology to Turtle
python -m src.cli.thalabus ontology export --format ttl -o EAM

# Export all ontologies to JSON-LD with a custom output path
python -m src.cli.thalabus ontology export --format jsonld --out output/all_ontologies.jsonld

Output files are written to output/ by default (e.g. output/FictionalStories_export.jsonld).

import — Import ontology schema from OWL or JSON-LD

python -m src.cli.thalabus ontology import --format <owl|ttl|jsonld> [--in FILEPATH] [--merge | --overwrite]

Imports ontology schema nodes into Neo4j from a previously exported file. Creates Ontology, EntityOntology, RelationshipOntology, OntologyAttribute, OntologySource, and KeywordCategory nodes, including their connecting relationships.

Option	Description	Default
--format	Input format: owl (RDF/XML), ttl (Turtle), jsonld	jsonld
--in	Input file path	output/ontology_import.<ext>
--merge	MERGE into existing data (idempotent)	✓ default
--overwrite	Use CREATE instead of MERGE (may create duplicates)	off

Examples:

# Re-import a previously exported JSON-LD file (merge mode)
python -m src.cli.thalabus ontology import --format jsonld --in output/FictionalStories_export.jsonld

# Import an OWL file
python -m src.cli.thalabus ontology import --format owl --in output/EAM_export.owl

# Import from the default input file (output/ontology_import.jsonld)
python -m src.cli.thalabus ontology import --format jsonld

Note: The default import mode is --merge, which safely updates existing nodes without deleting data. Use --overwrite only when you intentionally want to replace all matching nodes.

---

category

Manage categories (classification terms within ontologies).

Commands

ls — List categories

python -m src.cli.thalabus category ls [-o ONTOLOGY_ID] [--export [FILENAME]] [--import [FILENAME]] [-v] [-w] [-wc]

Lists all categories. Supports: - -o, --ontology: Filter by ontology - --export [FILENAME]: Export to CSV (uses default path if filename omitted) - --import [FILENAME]: Import from CSV (uses default path if filename omitted)

rm — Remove categories

python -m src.cli.thalabus category rm -o ONTOLOGY_ID [-y] [--all] [PATTERN]

Removes categories matching a regex pattern or all categories. Requires: - -o, --ontology: Ontology ID (required) - --all: Delete all categories (omit PATTERN) - -y, --yes: Skip confirmation prompt - PATTERN: Regular expression to match text_en field (ignored with --all)

---

query

Execute Thalabus queries against the dataset.

Command

query — Run a query

python -m src.cli.thalabus query [-o ONTOLOGY_ID] [-s DATASET_ID] [-r] [-u USER] [--text] [--perf] [-v] [-w] [-wc] <QUERY_STRING>

Executes a Thalabus query string. Options can appear before or after the query string. Options: - -o, --ontology: Restrict category matching to ontology - -s, --subset: Restrict search to dataset - -r, --no-rerank: Disable automatic reranking (enabled by default) - -u, --user: Resolve either User.username or User.id and filter results using that effective user's ACL permissions. If omitted, the query uses system/anonymous access. - --text: Perform exact text search (case-insensitive) instead of semantic search. Wraps the query in single quotes. - --perf: Collect and summarize PERF log entries after query completes

Examples:

# Semantic search with no reranking
python -m src.cli.thalabus query -r "Bob"

# Exact text search with no reranking
python -m src.cli.thalabus query -r --text Monaco

# Semantic search with ontology filter
python -m src.cli.thalabus query -r -o Juris "asylum"

# Query as a specific user, applying document ACL permissions
python -m src.cli.thalabus query -u test-user-2 "What did Bob do in the kitchen?"

# Flags after query string (also supported)
python -m src.cli.thalabus query "Bob" -r -o Juris

---

query-analyse

Analyze query results and categories.

Command

query-analyse — Analyze query

python -m src.cli.thalabus query-analyse [-o ONTOLOGY_ID] [-s DATASET_ID] [--text] [-v] [-w] [-wc] <QUERY_STRING>

Analyzes query results and matching categories. Options can appear before or after the query string. Options same as query (no reranking option available here).

---

innovator

Enterprise Architecture (EA) commands for diagram and element management.

Commands

diagram list — List EA diagrams

python -m src.cli.thalabus innovator diagram list [--type DIAGRAM_TYPE] [--offset OFFSET] [--limit LIMIT] [-v] [-w] [-wc]

Lists diagrams from the EA Neo4j database with pagination.

diagram migrate — Migrate diagrams to local database

python -m src.cli.thalabus innovator migrate diagram [--all | --type TYPE | --diagram DIAGRAM_ID] [--depth DEPTH]

Migrates diagrams from EA Neo4j into local database. Exactly one of: - --all: Migrate every diagram - --type TYPE: Migrate only diagrams with this label - --diagram DIAGRAM_ID: Migrate single diagram (Name or elementId)

Additional options: - --depth: Relationship hops to traverse (default: 1)

element list — List EA elements

python -m src.cli.thalabus innovator element list [--diagram DIAGRAM_ID] [--depth DEPTH] [--type ELEMENT_TYPE] [--offset OFFSET] [--limit LIMIT] [-v] [-w] [-wc]

Lists elements from EA Neo4j with optional diagram scoping and pagination.

element details — Show element properties

python -m src.cli.thalabus innovator element details <ELEMENT_ID> [-v] [-w] [-wc]

Shows full properties of a single element by Name or elementId.

---

doc

Document management (dossier-based utilities).

Commands

ls — List documents

python -m src.cli.thalabus doc ls [-d DOSSIER_ID] [DOSSIER_ID] [-v] [-w] [-wc]

Lists documents in a dossier.

show — Show documents for a dossier

python -m src.cli.thalabus doc show [DOSSIER_ID] [-i] [--details] [-d DOSSIER_ID] [-v] [-w] [-wc]

Shows documents with options: - -i, --ids: Print only document IDs (one per line) - --details: Include document title, type, and status fields

lscat — List categories for a document

python -m src.cli.thalabus doc lscat [DOCUMENT_ID] [-d DOSSIER_ID] [-v] [-w] [-wc]

Lists categories assigned to a document. If -d DOSSIER_ID is used, lists categories for all documents in dossier.

rmcat — Remove categories from documents

python -m src.cli.thalabus doc rmcat [-d DOSSIER_ID] [DOCUMENT_IDS...] [CATEGORY_TEXT_EN] [--all] [-v] [-w] [-wc]

Removes category/categories from document(s). Options: - -d DOSSIER_ID: Remove from all documents in dossier - DOCUMENT_IDS: Space or comma-separated document IDs - CATEGORY_TEXT_EN: Category name to remove (omit with --all) - --all: Remove ALL categories

cat — Upsert category for document(s)

python -m src.cli.thalabus doc cat [DOSSIER_ID] [CATEGORY_ARG] [-d DOSSIER_ID] [-v] [-w] [-wc]

Assigns or updates category for document(s). - CATEGORY_ARG: Format as <CATEGORY_TEXT_EN> or <CATEGORY_TEXT_EN>=<VALUE> - -d DOSSIER_ID: Apply to all documents in dossier (overrides positional dossier_id)

categorize — Categorize documents using DocumentCategorizer

python -m src.cli.thalabus doc categorize [-o ONTOLOGY_ID] [-d DOSSIER_ID] [-f] [-l LIMIT] [--only-categorized] [--only-without-category] [--category CATEGORY] [-v] [-w] [-wc] [TARGETS]

Auto-categorizes documents. Options: - -o, --ontology: Ontology ID (optional if dossier has one) - -d, --dossier: Dossier ID (optional if document IDs provided) - -f, --force: Remove existing categories before categorization - -l, --limit: Limit number of documents to categorize - --only-categorized: Re-categorize only docs with multiple existing categories (requires -d and --category) - --only-without-category: Categorize only docs missing all categories, or missing a specific category when used with --category (requires -d) - --category CATEGORY: Category text_en to re-categorize (required with --only-categorized, optional with --only-without-category) - --clean: Remove existing category values before re-categorization - --dry-run: Count documents to be categorized without making any changes (shows only the total count) - TARGETS: Dossier ID or comma-separated document IDs

load — Create a new document from a text file

python -m src.cli.thalabus doc load <FILENAME> [-v] [-w] [-wc]

Creates a brand-new Document node from a .txt file (only .txt is currently supported; other extensions are rejected). The document ID is always auto-generated in the format docid-NNNN — there is no way to target an existing document ID with this command, and running it twice on the same file creates two separate documents. The title is derived from the filename (without extension).

own — Configure full document ownership

python -m src.cli.thalabus doc own <DOCUMENT_IDS...> --user USERNAME_OR_ID

Assigns OWNS and all six ACL permissions (READ, SHARING, DELETE, ADD, UPDATE, and OWNERSHIP) to the selected user's hidden user group. This is intended for ACL fixture/bootstrap setup.

python -m src.cli.thalabus doc own docid-100 docid-101 docid-102 --user test-user-1

rm — Remove one or more documents (prompts for confirmation unless -y provided)

python -m src.cli.thalabus doc rm <DOCUMENT_IDS...> [-y] [-u USER] [-v] [-w] [-wc]

Removes one or more documents and their related nodes (chapters, paragraphs, images, summaries). Options: - <DOCUMENT_IDS...>: One or more document IDs to remove (space-separated, required) - -y, --yes: Skip confirmation prompt - -u, --user: User.username or User.id for ACL testing (optional; defaults to system/anonymous access) - -v, --verbose: Show verbose output - -w, --write: Write output to .md file and open in VS Code - -wc, --write-clear: Clear output directory before writing

Examples:

# Remove single document with confirmation
python -m src.cli.thalabus doc rm my-doc

# Remove multiple documents without confirmation
python -m src.cli.thalabus doc rm doc1 doc2 doc3 -y

# Remove documents with specific user for ACL testing
python -m src.cli.thalabus doc rm testdoc -y --user alice

save — Save document text to file

python -m src.cli.thalabus doc save <DOCUMENT_ID> [FILENAME] [-v] [-w] [-wc]

Saves document text from Neo4j to file (filename optional, defaults to constructed name).

hierarchy — Show document hierarchy

python -m src.cli.thalabus doc hierarchy <DOCUMENT_ID> [-v] [-w] [-wc]

Displays the Document → Chapter → Paragraph hierarchy structure for a document, showing all nested levels with their text sizes and enhanced text sizes. Options: - <DOCUMENT_ID>: Document ID to show hierarchy for (required) - -v, --verbose: Show formatted output - -w, --write: Write output to .md file and open in VS Code - -wc, --write-clear: Clear output directory before writing

ask — Ask the LLM a question about document(s)

python -m src.cli.thalabus doc ask <DOCUMENT_IDS> <QUESTION> [-v] [-w] [-wc]

Uses the default LLM model to answer a question about one or more documents. The LLM analyzes the full document text and provides contextual answers. Options: - <DOCUMENT_IDS>: Single document ID, comma-separated, or space-separated list (e.g., docid-927 or docid-927,docid-1010) - <QUESTION>: Question or query to ask about the document(s) — can be multiple words - -v, --verbose: Show formatted output - -w, --write: Write output to .md file and open in VS Code - -wc, --write-clear: Clear output directory before writing

Examples:

# Ask about a single document
python -m src.cli.thalabus doc ask docid-927 "Does this document contain BVGE 2014/28?"

# Ask about multiple documents
python -m src.cli.thalabus doc ask "docid-927,docid-1010" "Which documents mention BVGE 2008/34?"

# Write output to markdown file
python -m src.cli.thalabus doc ask docid-927 "Summarize the key points in this document" -w

# Use with comma or space separation
python -m src.cli.thalabus doc ask docid-927 docid-1010 "Compare these two documents"

---

dossier

Dossier (case) management.

Commands

ls — List dossiers

python -m src.cli.thalabus dossier ls [DOSSIER_ID] [-v] [-w] [-wc]

Lists dossiers or shows details for a specific dossier.

create — Create a dossier (idempotent)

python -m src.cli.thalabus dossier create <DOSSIER_ID> -n/--name NAME [-d/--description DESCRIPTION]

Creates a dossier. Safe to run multiple times—if the dossier already exists, the command does nothing (idempotent behavior). Options: - DOSSIER_ID: Unique dossier identifier (required, positional) - -n, --name: Dossier name (required) - -d, --description: Dossier description (optional)

Examples:

# Create a new dossier
python -m src.cli.thalabus dossier create case-001 --name "Asylum Case" --description "Kosovo applicant"

# Run again—no error, just confirms it already exists
python -m src.cli.thalabus dossier create case-001 --name "Asylum Case" --description "Kosovo applicant"
# Output: Dossier already exists: case-001

rm — Remove a dossier

python -m src.cli.thalabus dossier rm <DOSSIER_ID> [-y] [-v] [-w] [-wc]

Removes a dossier. Use -y, --yes to skip confirmation.

stat — Inspect category usage statistics

python -m src.cli.thalabus dossier stat -d DOSSIER_ID --category CATEGORY_TEXT_EN [-v] [-w] [-wc]

Shows category usage statistics for a specific category in a dossier.

---

test

RAG (Retrieval-Augmented Generation) test question management.

Commands

generate — Generate RAG test questions

python -m src.cli.thalabus test generate <DOSSIER_ID> [-o ONTOLOGY_ID] [--limit LIMIT] [--per-category QUESTIONS_PER_CATEGORY] [--questions TARGET_QUESTIONS] [--report REPORT_FILE] [-v] [-w] [-wc]

Generates RAG test questions for a dossier. Options: - -o, --ontology: Ontology ID (auto-discovered if omitted) - --limit: Max documents to generate tests for (default: 64) - --per-category: Questions per category (default: 3) - --questions: Target number of valid questions (default: 12) - --report: Output report file path (default: reports/rag_test_generation_report_<dossier_id>.txt)

delete — Delete test questions

python -m src.cli.thalabus test delete <DOSSIER_ID> [-y] [-v] [-w] [-wc]

Deletes all test questions from a dossier. Use -y, --yes to skip confirmation.

run — Execute RAG tests

python -m src.cli.thalabus test run <DOSSIER_ID> [-o ONTOLOGY_ID] [--limit LIMIT] [-v] [-w] [-wc]

Executes RAG tests from a dossier. Options: - -o, --ontology: Ontology ID (auto-discovered if omitted) - --limit: Max tests to run (-1 for all, default: -1)

---

template

Document template management (XML-based reasoning templates).

Commands

list — List all templates

python -m src.cli.thalabus template list [-v] [-w] [-wc]

Lists all available document templates.

show — Show template content

python -m src.cli.thalabus template show -t TEMPLATE_ID [-v] [-w] [-wc]

Shows the text content of a template (required: -t TEMPLATE_ID).

load — Load template from XML file

python -m src.cli.thalabus template load <FILENAME> [-t TEMPLATE_ID] [-v] [-w] [-wc]

Loads template from XML file into Neo4j. If relative path, searches Examples/ directory. - -t TEMPLATE_ID: Optional; extracted from XML if omitted

verify — Verify template XML against XSD

python -m src.cli.thalabus template verify <FILENAME> [--xsd XSD_PATH] [-v] [-w] [-wc]

Verifies template XML against XSD schema. - --xsd: Optional; defaults to Examples/reasoning_template.xsd

---

reasoning

Reasoning document management (structured decision documents).

Commands

load — Load reasoning document from XML

python -m src.cli.thalabus reasoning load [DOCUMENT_ID] <FILENAME> [-v] [-w] [-wc]

Loads reasoning document from XML file into Neo4j (document_id optional, extracted from XML if omitted).

save — Save reasoning document to XML

python -m src.cli.thalabus reasoning save [DOCUMENT_ID] <FILENAME> [-d DOSSIER_ID] [-v] [-w] [-wc]

Saves reasoning document from Neo4j to XML file. - -d DOSSIER_ID: Auto-discover reasoning document from dossier

status — Show division status

python -m src.cli.thalabus reasoning status [DOCUMENT_ID] [-d DOSSIER_ID] [-v] [-w] [-wc]

Shows status of divisions in a reasoning document. - -d DOSSIER_ID: Auto-discover from dossier

show — Show division XML

python -m src.cli.thalabus reasoning show [DOCUMENT_ID] [DIVISION_ID] [-d DOSSIER_ID] [-v] [-w] [-wc]

Shows full XML of divisions (all or specific division by ID/index). - DIVISION_ID: Specific division ID or index (optional; all if omitted) - -d DOSSIER_ID: Auto-discover from dossier

reset — Reset divisions to open status

python -m src.cli.thalabus reasoning reset [DOCUMENT_ID] [DIVISION_IDS...] [-d DOSSIER_ID] [-c] [-v] [-w] [-wc]

Resets divisions: deletes tasks/results and sets to open status. - DIVISION_IDS: Optional; resets all active divisions if omitted - -d DOSSIER_ID: Auto-discover from dossier - -c, --clear: Also clear issues, recommendations, and summary

complete — Complete a division

python -m src.cli.thalabus reasoning complete [DOCUMENT_ID] [DIVISION_INDEX] [-d DOSSIER_ID] [-v] [-w] [-wc]

Sets division and all its tasks to complete status. - DIVISION_INDEX: 1-based division index (as shown in status command) - -d DOSSIER_ID: Auto-discover from dossier

---

hint

Agent hint management (hints stored in Neo4j, synced via ThalabusWeb API).

Commands

export — Export hints to JSON

python -m src.cli.thalabus hint export [-f FILE] [-s SERVER] [-t TOKEN] [-v] [-w] [-wc]

Exports all hints from server to JSON file. - -f, --file: Output file path (default: Documentation/Hints/hints.json) - -s, --server: ThalabusWeb server host:port (default: localhost:5210) - -t, --token: API token (default: THALABUS_TOKEN from .env)

import — Import hints from JSON

python -m src.cli.thalabus hint import [-f FILE] [-s SERVER] [-t TOKEN] [-v] [-w] [-wc]

Imports hints from JSON file into server (upsert by id). - -f, --file: Input file path (default: Documentation/Hints/hints.json) - -s, --server: ThalabusWeb server host:port - -t, --token: API token

delete — Delete a single hint

python -m src.cli.thalabus hint delete <HINT_ID> [-s SERVER] [-t TOKEN] [-v] [-w] [-wc]

Deletes a single hint by ID.

delete-all — Delete all hints

python -m src.cli.thalabus hint delete-all --confirm [-s SERVER] [-t TOKEN] [-v] [-w] [-wc]

Deletes all hints from server. Requires --confirm flag.

---

kb

Knowledge base defaults management (Cypher seed script export/import).

Commands

export — Export knowledge base defaults

python -m src.cli.thalabus kb export [-f FILE] [--llmsettings LLMSETTINGS_PATH] [-v] [-w] [-wc]

Exports knowledge_base_defaults from LlmSettings.json to .txt file. - -f, --file: Output file path (default: Documentation/Ontologies/KnowledgeBaseDefaults.txt) - --llmsettings: Path to LlmSettings.json (default: ../ThalabusWeb/Configuration/LlmSettings.json)

import — Import knowledge base defaults

python -m src.cli.thalabus kb import [-f FILE] [--llmsettings LLMSETTINGS_PATH] [-v] [-w] [-wc]

Imports knowledge_base_defaults from .txt file back into LlmSettings.json. - -f, --file: Input file path (default: Documentation/Ontologies/KnowledgeBaseDefaults.txt) - --llmsettings: Path to LlmSettings.json

---

Architecture

The CLI is composed as a single class ThalabusCLI inheriting from resource-specific mixin classes:

• OntologyCommandsMixin — ontology operations
• CategoryCommandsMixin — category operations
• QueryCommandsMixin — query execution
• KbCommandsMixin — knowledge base defaults
• DocCommandsMixin — document utilities
• DossierCommandsMixin — dossier management
• TestCommandsMixin — RAG test generation/execution
• TemplateCommandsMixin — template management
• ReasoningCommandsMixin — reasoning document management
• InnovatorCommandsMixin — EA/Innovator commands
• HintCommandsMixin — hint import/export

Each mixin is defined in a separate file (cli_<resource>.py) and implements the handler methods for its resource's commands.

Output Options

All commands support optional output formatting:

• Markdown export (-w, --write): Writes structured output to a .md file in the output/ directory and attempts to open in VS Code
• Clear output (-wc, --write-clear): Removes previously generated .md files before writing
• Verbose (-v, --verbose): Shows more details in output

Logging

• Debug mode (--debug): Enables DEBUG-level console logging (default: WARNING)
• LLM output (--llm-out): Includes LLM output messages in logs (excluded by default to reduce noise)

---

Examples

Generate RAG tests for a dossier

python -m src.cli.thalabus test generate dossier-123 --limit 20 --per-category 5 -w

List all categories in an ontology

python -m src.cli.thalabus category ls -o ontology-456 -v

Query and analyze results

python -m src.cli.thalabus query "search for COUNTRY_OF_ORIGIN in asylum cases" -o ontology-456 -w

Categorize all documents in a dossier

python -m src.cli.thalabus doc categorize -d dossier-789 -o ontology-456 -f

Export hints for backup

python -m src.cli.thalabus hint export -f ./backup_hints.json

Check reasoning document divisions

python -m src.cli.thalabus reasoning status -d dossier-789