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

```bash
# 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](commands.md) for complete command documentation and [Workflows](workflows.md) 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

```bash
# 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](nushell-scripts.md) 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

```bash
cargo install --path crates/kogral-cli
```

### NuShell Scripts

Scripts are in the repository at `scripts/`:

```bash
# 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](../config/overview.md) 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:

```bash
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:

```bash
# 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:

```yaml
# 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:

```bash
cargo install --path crates/kogral-cli
```

### "nu: command not found"

Install NuShell:

```bash
# macOS
brew install nushell

# Linux
cargo install nu

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

### Scripts not executable

Make scripts executable:

```bash
chmod +x scripts/*.nu
```

Or run directly with `nu`:

```bash
nu scripts/kogral-sync.nu
```

## Next Steps

- [Commands Reference](commands.md) - Detailed CLI command documentation
- [Workflows](workflows.md) - Task-oriented guides for common operations
- [NuShell Scripts](nushell-scripts.md) - Advanced maintenance and automation