kogral/docs/cli/overview.md

CLI Overview

KOGRAL provides two complementary command-line interfaces for knowledge base management:

1. kogral-cli - The main binary with 13 commands for node operations, search, and config
2. NuShell Scripts - Maintenance and automation scripts for advanced operations

kogral-cli Binary

The Rust CLI tool (cargo install --path crates/kogral-cli) provides primary operations:

Core Commands

• init - Initialize .kogral/ directory in project
• add - Create new nodes (note, decision, guideline, pattern, journal)
• search - Text and semantic search across knowledge base
• link - Create relationships between nodes
• list - List all nodes with filtering options
• show - Display node details with relationships
• delete - Remove nodes from knowledge base
• graph - Visualize knowledge graph structure
• config - Manage configuration settings
• sync - Sync filesystem ↔ SurrealDB (underlying operation)
• import - Import from Logseq format
• export - Export to Logseq/JSON/Markdown
• serve - Start MCP server for Claude Code integration

Quick Start

# Initialize project
kogral init

# Create a decision note
kogral add --type decision "API Authentication Strategy"

# Search for related content
kogral search "authentication" --limit 10

# Create relationships
kogral link "api-auth" --relates-to "api-design" --depends-on "security-policy"

# View the graph
kogral graph --output graph.svg

See Commands Reference for complete command documentation and Workflows for task-oriented guides.

NuShell Scripts

Production-ready scripts written in NuShell for maintenance and automation tasks:

Script	Purpose
kogral-sync.nu	Bidirectional sync (filesystem ↔ SurrealDB)
kogral-reindex.nu	Rebuild embeddings index (fastembed, OpenAI, Claude, Ollama)
kogral-import-logseq.nu	Import from Logseq graphs
kogral-export-logseq.nu	Export to Logseq format
kogral-migrate.nu	Schema migrations (version management)

Quick Start

# Reindex with local embeddings
nu scripts/kogral-reindex.nu

# Import from Logseq
nu scripts/kogral-import-logseq.nu ~/Logseq/mydb

# Export to Logseq
nu scripts/kogral-export-logseq.nu ~/logseq-export

# Sync to SurrealDB
nu scripts/kogral-sync.nu --direction to-storage

See NuShell Scripts for detailed documentation on all scripts, options, and examples.

CLI vs Scripts: When to Use Each

Use kogral-cli for

• Daily operations - Adding notes, creating relationships, searching
• Interactive workflows - Real-time graph operations
• Quick queries - Text/semantic search with immediate results
• Configuration - Viewing and updating settings
• Single-file operations - Creating, viewing, deleting nodes

Use NuShell Scripts for

• Batch operations - Processing many files at once
• Automation - Scheduled tasks via cron/systemd
• Storage sync - Keeping filesystem and SurrealDB in sync
• Format migration - Importing/exporting entire graphs
• Maintenance - Reindexing, schema upgrades
• CI/CD pipelines - Automated knowledge base updates

Installation

kogral-cli

cargo install --path crates/kogral-cli

NuShell Scripts

Scripts are in the repository at scripts/:

# Direct execution
nu scripts/kogral-sync.nu --help

# Via justfile
just scripts::sync
just scripts::reindex
just scripts::import
just scripts::export

Configuration

Both CLI and scripts respect the KOGRAL configuration system:

• Primary config: .kogral/config.toml or via Nickel schemas
• Storage backend: Selected in config (filesystem, SurrealDB, or both)
• Embedding provider: Configured for reindexing operations
• Environment variables: Used for API credentials (OPENAI_API_KEY, ANTHROPIC_API_KEY)

See Configuration for details.

Error Handling

Both interfaces follow clean error patterns:

kogral-cli:

• Clear error messages with context
• Exit codes: 0 (success), 1 (error)
• Help text via --help on any command

NuShell Scripts:

• Production patterns without try-catch wrapping
• Exit codes: 0 (success), 1 (fatal error)
• Dry-run mode for all destructive operations
• Direct error propagation (errors are visible)

Performance Notes

• CLI operations: Sub-second for single nodes, scales linearly
• Scripts: Optimize for batch processing with configurable parameters
• Search: Text search is instant; semantic search depends on provider
• Reindexing: Scales with node count and API latency (use batches to control)

Integration

With justfile

Most operations can be run via justfile recipes:

just dev::init          # Initialize project
just dev::add-note      # Create a note
just dev::search        # Search knowledge base
just scripts::sync      # Run sync script
just scripts::reindex   # Run reindex script

With Git workflows

Knowledge base is git-friendly:

# Commit changes
git add .kogral/
git commit -m "Update architecture decisions"

# Sync to SurrealDB
nu scripts/kogral-sync.nu --direction to-storage

# Export for sharing
nu scripts/kogral-export-logseq.nu ./share/

With CI/CD

Scripts are designed for automation:

# GitHub Actions example
- name: Reindex embeddings
  run: nu scripts/kogral-reindex.nu --provider fastembed

- name: Export knowledge base
  run: nu scripts/kogral-export-logseq.nu ./artifacts/

- name: Sync to storage
  run: nu scripts/kogral-sync.nu

Troubleshooting

"kogral: command not found"

Install the CLI:

cargo install --path crates/kogral-cli

"nu: command not found"

Install NuShell:

# macOS
brew install nushell

# Linux
cargo install nu

# Or see https://www.nushell.sh/book/installation.html

Scripts not executable

Make scripts executable:

chmod +x scripts/*.nu

Or run directly with nu:

nu scripts/kogral-sync.nu

Next Steps

• Commands Reference - Detailed CLI command documentation
• Workflows - Task-oriented guides for common operations
• NuShell Scripts - Advanced maintenance and automation