CLI Reference

The Thalo CLI (thalo) provides commands for managing your knowledge base.

Installation

pnpm add -g @rejot-dev/thalo-cli

Commands

thalo init

Initialize a new Thalo knowledge base in the current directory.

thalo init [directory]

Creates:

• entities.thalo - Entity schema definitions
• AGENTS.md - AI agent instructions
• personal-bio.md - Example synthesis file

Options:

• -n, --dry-run - Show what would be created without making changes
• -f, --force - Overwrite existing files

Example:

mkdir my-knowledge
cd my-knowledge
thalo init

thalo check

Validate Thalo files against their schemas.

thalo check [paths...]

Options:

• paths - Files or directories to check (defaults to current directory)
• -q, --quiet - Only show errors, suppress warnings and info
• -f, --format <format> - Output format: default, json, compact, or github
• --severity <level> - Minimum severity to report: error, warning, or info
• --max-warnings <n> - Exit with error if warnings exceed threshold
• --rule <rule>=<severity> - Set rule severity (e.g., unknown-entity=off)
• -w, --watch - Watch files for changes and re-run
• --file-type <types> - Comma-separated list of file types (default: md,thalo)

What it validates:

• Syntax correctness
• Required metadata fields
• Field type compatibility
• Required sections
• Link references
• Enum value validity

Example:

# Check all files
thalo check

# Check specific files
thalo check entries.thalo entities.thalo

# Watch mode
thalo check --watch

# CI mode with GitHub annotations
thalo check --format github

# Disable a specific rule
thalo check --rule unknown-entity=off

Exit codes:

• 0 - All checks passed
• 1 - Validation errors found

thalo format

Format Thalo and Markdown files using Prettier.

thalo format [paths...]

Options:

• paths - Files or directories to format (defaults to current directory)
• -c, --check - Check if files are formatted (exit 1 if not)
• -w, --write - Write formatted output back to files (default: true)
• --file-type <types> - Comma-separated list of file types (default: md,thalo)

Example:

# Format all files
thalo format

# Check formatting without making changes
thalo format --check

# Format specific files
thalo format entries.thalo notes/

thalo actualize

Generate synthesized content from syntheses.

thalo actualize [paths...]

Options:

• paths - Files or directories to check for syntheses (defaults to current directory)

Example:

# Actualize all syntheses
thalo actualize

# Actualize syntheses in specific directory
thalo actualize ./my-knowledge

thalo query

Query entries by entity type, tags, links, or metadata.

thalo query "<query>" [paths...]

Query Syntax:

• Entity only: lore - All entries of type
• Tag filter: lore where #career - Entries with tag
• Link filter: opinion where ^my-topic - Entries with link
• Field filter: lore where type = "fact" - Entries matching field value
• Combined: lore where #career and type = "insight" - Multiple conditions (AND)

Options:

• -f, --format <format> - Output format: default, json, or raw
• -n, --limit <number> - Maximum number of results to show

Examples:

# Query all lore entries
thalo query "lore"

# Query entries with a specific tag
thalo query "lore where #career"

# Query entries with a field value
thalo query 'lore where type = "insight"'

# Query entries with a link
thalo query "opinion where ^my-topic"

# Combine conditions
thalo query 'lore where #career and type = "fact"'

# Output as JSON
thalo query "lore" --format json

# Show raw entry text
thalo query "lore where #career" --format raw

# Limit results
thalo query "lore" --limit 5

# Query specific directory
thalo query "lore" ./my-knowledge-base

thalo rules list

Display available validation rules.

thalo rules list

Options:

• -s, --severity <level> - Filter by severity: error, warning, or info
• -c, --category <cat> - Filter by category: instance, link, schema, metadata, or content
• --json - Output as JSON

Example:

# List all rules
thalo rules list

# Filter by severity
thalo rules list --severity error

# Output as JSON
thalo rules list --json

thalo lsp

Start the Language Server Protocol server for editor integration.

thalo lsp

This command is typically invoked by editors (VS Code, etc.) automatically. Communication happens over stdio.

Options:

• --stdio - Use stdio transport (default, accepted for compatibility)

thalo setup-merge-driver

Configure Git to use the semantic merge driver for Thalo files.

thalo setup-merge-driver

Options:

• -g, --global - Configure globally in ~/.gitconfig
• --check - Check if merge driver is configured
• --uninstall - Remove merge driver configuration

Example:

# Setup for current repository
thalo setup-merge-driver

# Setup globally
thalo setup-merge-driver --global

# Check configuration
thalo setup-merge-driver --check

# Remove configuration
thalo setup-merge-driver --uninstall

thalo merge-driver

Git merge driver for Thalo files. This command is called by Git during merges and is not intended for direct use.

thalo merge-driver <base> <ours> <theirs> [path]

Options:

• -q, --quiet - Suppress output
• -v, --verbose - Show detailed conflict information
• --diff3 - Use diff3 conflict style (show base)

Global Options

--help, -h

Display help information.

thalo --help
thalo check --help

--version, -v

Display version information.

thalo --version

Workflow Examples

Daily Workflow

# 1. Check your entries before committing
thalo check

# 2. Format files
thalo format

# 3. If valid, commit to git
git add entries.thalo
git commit -m "Add new opinion on TypeScript"

Querying Your Knowledge

# Find all career-related insights
thalo query 'lore where #career and type = "insight"'

# Export entries as JSON for processing
thalo query "opinion" --format json > opinions.json

# Get raw text of specific entries
thalo query "lore where ^my-topic" --format raw

Setting Up a New Knowledge Base

# 1. Create directory
mkdir my-knowledge
cd my-knowledge

# 2. Initialize
thalo init

# 3. Setup merge driver for better git merges
thalo setup-merge-driver

# 4. Edit entries and validate
thalo check

Working with Syntheses

# 1. Define a synthesis in a markdown file
# 2. Actualize it
thalo actualize

# 3. Review generated content

CI/CD Integration

# Check with GitHub Actions annotations
thalo check --format github

# Fail on any warnings
thalo check --max-warnings 0

# Check formatting
thalo format --check

Error Messages

The CLI provides helpful error messages:

Error: Missing required field 'confidence' in entry at line 5
  Entity: opinion
  Entry: ^ts-enums
  File: entries.thalo

Common errors:

• Missing required field - Add the required metadata field
• Invalid type - Check the field type matches the schema
• Missing required section - Add the required section
• Invalid link reference - Ensure the linked entry exists
• Invalid enum value - Use one of the allowed enum values

Integration with Git

Thalo files are plain text, making them perfect for version control:

# Add .thalo files to git
git add *.thalo

# Commit changes
git commit -m "Add new knowledge entries"

# View history
git log -- entries.thalo

For smarter merges, set up the Thalo merge driver:

thalo setup-merge-driver

This enables semantic merging that understands entry boundaries, reducing conflicts when multiple people edit the same file.

Editor Integration

For the best experience, use the VSCode extension which provides:

• Real-time validation
• Autocomplete
• Diagnostics
• Go-to-definition

The CLI is still useful for:

• CI/CD validation
• Batch operations
• Scripting workflows
• Formatting files

Next Steps

• Learn about syntax
• Explore entity definitions
• See examples