243 lines
6.2 KiB
Markdown
243 lines
6.2 KiB
Markdown
# 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
|