CLI Reference

Complete reference for the Thalo command-line interface

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
  • references.thalo - Starter reference entry

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

Show pending synthesis updates and generate prompts for AI-assisted content generation.

thalo actualize [links...]

The command loads all files from the current directory and finds syntheses that need updating based on changed source entries. It uses git-based change tracking when available, falling back to timestamp-based tracking otherwise.

Arguments:

  • links - Link IDs of synthesis definitions to actualize (e.g., ^my-summary). If omitted, all syntheses are checked. The ^ prefix is optional.

Options:

  • -i, --instructions <template> - Custom instructions template. Placeholders: {file}, {linkId}, {checkpoint}, {timestamp}

Output:

For each synthesis with pending updates, the command outputs:

  1. Synthesis info - Title, target link, source queries
  2. User prompt - The prompt defined in the synthesis
  3. Changed entries - Raw text of entries that have changed since last actualization
  4. Instructions - Steps to update the synthesis with a new checkpoint

Example:

# Check all syntheses for pending updates
thalo actualize

# Actualize a specific synthesis by link ID
thalo actualize my-summary

# With ^ prefix (must be quoted to avoid shell interpretation)
thalo actualize "^my-summary"

# Actualize multiple specific syntheses
thalo actualize summary-a summary-b

Change Tracking:

The actualize command tracks which entries have changed since the last actualization:

  • Git mode (default when in a git repo): Compares entries against the checkpoint commit hash stored in the last actualize-synthesis entry
  • Timestamp mode (fallback): Uses entry timestamps to determine what's new

After updating a synthesis, add an actualize-synthesis entry with a checkpoint metadata field to mark the current state:

2026-01-15T10:00Z actualize-synthesis ^my-summary
  checkpoint: "git:abc1234..."

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

# Initialize your knowledge base and cd into it
thalo init my-knowledge && cd my-knowledge

# Edit entries and validate
thalo check

Working with Syntheses

# 1. Define a synthesis in a markdown file with define-synthesis
# 2. Check for pending updates
thalo actualize

# 3. If updates are needed, the command outputs:
#    - The synthesis prompt
#    - Changed source entries
#    - Instructions for updating

# 4. Update the synthesis content and add an actualize entry
#    with the checkpoint value from the instructions

# 5. Actualize a specific synthesis
thalo actualize my-summary

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

Change Tracking

How Thalo tracks changes for synthesis actualization

Scripting API

Automate and extend your knowledge base with the Thalo scripting API

On this page

CLI ReferenceInstallationCommandsthalo initthalo checkthalo formatthalo actualizethalo querythalo rules listthalo lspthalo setup-merge-driverthalo merge-driverGlobal Options--help, -h--version, -vWorkflow ExamplesDaily WorkflowQuerying Your KnowledgeSetting Up a New Knowledge BaseWorking with SynthesesCI/CD IntegrationError MessagesIntegration with GitEditor IntegrationNext Steps