KotaDB CLI Usage Guide¶

KotaDB provides a simple command-line interface for interacting with the document database.

Building the CLI¶

First, build the project:

cd kota-db
cargo build --release

The CLI binary will be available at target/release/kotadb.

Basic Usage¶

# Run with default database location (./kota-db-data)
kotadb <command>

# Specify custom database location
kotadb --db-path /path/to/database <command>

Commands¶

Insert a Document¶

# Insert with inline content
kotadb insert "/docs/readme.md" "Project README" "This is the content"

# Insert with piped content
echo "This is the content" | kotadb insert "/docs/readme.md" "Project README"

# Insert from file
cat document.txt | kotadb insert "/docs/document.md" "My Document"

Get a Document¶

# Get by ID (UUID format)
kotadb get "123e4567-e89b-12d3-a456-426614174000"

Update a Document¶

# Update title only
kotadb update "123e4567-e89b-12d3-a456-426614174000" --title "New Title"

# Update path only
kotadb update "123e4567-e89b-12d3-a456-426614174000" --path "/docs/new-path.md"

# Update content from stdin
echo "New content" | kotadb update "123e4567-e89b-12d3-a456-426614174000" --content -

# Update everything
kotadb update "123e4567-e89b-12d3-a456-426614174000" \
  --path "/docs/updated.md" \
  --title "Updated Title" \
  --content "New content"

Delete a Document¶

kotadb delete "123e4567-e89b-12d3-a456-426614174000"

Search Documents¶

# Search all documents (default)
kotadb search

# Search with query text
kotadb search "machine learning"

# Search with limit
kotadb search "rust" --limit 20

# Search with tags
kotadb search --tags "rust,database"

# Combined search
kotadb search "learning" --tags "ml,ai" --limit 5

List All Documents¶

# List with default limit (50)
kotadb list

# List with custom limit
kotadb list --limit 100

Database Statistics¶

kotadb stats

Examples¶

Example 1: Managing Documentation¶

# Create a new document
echo "# KotaDB Documentation

## Overview
KotaDB is a custom database designed for distributed human-AI cognition.

## Features
- Document storage with metadata
- Full-text search
- Tag-based filtering
" | kotadb insert "/docs/kotadb-overview.md" "KotaDB Overview"

# Output:
# ✅ Document inserted successfully!
#    ID: f47ac10b-58cc-4372-a567-0e02b2c3d479
#    Path: /docs/kotadb-overview.md
#    Title: KotaDB Overview

# Search for it
kotadb search "cognition"

# Update it
kotadb update "f47ac10b-58cc-4372-a567-0e02b2c3d479" --title "KotaDB Overview - Updated"

Example 2: Batch Import¶

# Import multiple markdown files
for file in *.md; do
    title=$(basename "$file" .md | sed 's/-/ /g')
    kotadb insert "/imported/$file" "$title" < "$file"
done

Example 3: Export Document¶

# Get document and save to file
kotadb get "f47ac10b-58cc-4372-a567-0e02b2c3d479" > exported-doc.txt

Output Format¶

Insert Command¶

✅ Document inserted successfully!
   ID: f47ac10b-58cc-4372-a567-0e02b2c3d479
   Path: /docs/readme.md
   Title: Project README

Get Command¶

📄 Document found:
   ID: f47ac10b-58cc-4372-a567-0e02b2c3d479
   Path: /docs/readme.md
   Title: Project README
   Size: 1024 bytes
   Created: 2024-01-15 10:30:00 UTC
   Updated: 2024-01-15 10:30:00 UTC

--- Content ---
This is the document content...

Search Command¶

🔍 Found 3 documents:

📄 Machine Learning Papers
   ID: f47ac10b-58cc-4372-a567-0e02b2c3d479
   Path: /research/ml-papers.md
   Size: 2048 bytes

📄 Learning Rust
   ID: 550e8400-e29b-41d4-a716-446655440000
   Path: /tutorials/rust.md
   Size: 1536 bytes

Stats Command¶

📊 Database Statistics:
   Total documents: 42
   Total size: 125952 bytes
   Average size: 2998 bytes

Error Handling¶

The CLI provides clear error messages:

Invalid document ID: "Invalid document ID format"
Document not found: "❌ Document not found"
Invalid path: "Path cannot be empty"
Invalid title: "Title cannot be empty"

Tips¶

Use pipes: The CLI is designed to work well with Unix pipes for content input
UUID format: Document IDs must be valid UUIDs (e.g., 123e4567-e89b-12d3-a456-426614174000)
Path format: Paths should start with / (e.g., /docs/readme.md)
Tag format: Multiple tags should be comma-separated without spaces
Content input: Use - with --content flag to read from stdin

Troubleshooting¶

Database not found¶

# Create the database directory first
mkdir -p ./kota-db-data

Permission denied¶

# Ensure you have write permissions
chmod -R u+w ./kota-db-data

Invalid UTF-8 content¶

The CLI expects UTF-8 encoded text. For binary files, consider base64 encoding first.