osiris/QUICKSTART.md

OSIRIS Quick Start Guide

Get up and running with OSIRIS in 5 minutes!

Prerequisites

• Rust toolchain (1.70+)
• HeroDB running on localhost:6379

Step 1: Start HeroDB

cd /path/to/herodb
cargo run --release -- --dir ./data --admin-secret mysecret --port 6379

Keep this terminal open.

Step 2: Build OSIRIS

Open a new terminal:

cd /path/to/osiris
cargo build --release

Step 3: Initialize OSIRIS

./target/release/osiris init --herodb redis://localhost:6379

Output:

✓ OSIRIS initialized
  Config: /Users/you/.config/osiris/config.toml

Step 4: Create Your First Namespace

./target/release/osiris ns create notes

Output:

✓ Created namespace 'notes' (DB 1)

Step 5: Add Your First Object

echo "OSIRIS is awesome!" | \
  ./target/release/osiris put notes/first-note - \
  --title "My First Note" \
  --tags topic=osiris,mood=excited

Output:

✓ Stored notes/first-note

Step 6: Search for Your Object

./target/release/osiris find "awesome" --ns notes

Output:

Found 1 result(s):

1. first-note (score: 0.50)
   OSIRIS is awesome!

Step 7: Retrieve Your Object

./target/release/osiris get notes/first-note

Output (JSON):

{
  "id": "first-note",
  "ns": "notes",
  "meta": {
    "title": "My First Note",
    "tags": {
      "mood": "excited",
      "topic": "osiris"
    },
    "created": "2025-10-20T10:30:00Z",
    "updated": "2025-10-20T10:30:00Z",
    "size": 18
  },
  "text": "OSIRIS is awesome!"
}

Step 8: Try More Features

Add a note from a file

echo "This is a longer note about OSIRIS features" > /tmp/note.txt
./target/release/osiris put notes/features /tmp/note.txt \
  --title "OSIRIS Features" \
  --tags topic=osiris,type=documentation

Search with filters

./target/release/osiris find --ns notes --filter topic=osiris

Get raw content

./target/release/osiris get notes/first-note --raw

View statistics

./target/release/osiris stats --ns notes

List all namespaces

./target/release/osiris ns list

Common Commands Cheat Sheet

# Initialize
osiris init --herodb redis://localhost:6379

# Namespace management
osiris ns create <name>
osiris ns list
osiris ns delete <name>

# Object operations
osiris put <ns>/<name> <file> [--tags k=v,...] [--title "..."] [--mime "..."]
osiris get <ns>/<name> [--raw] [--output file]
osiris del <ns>/<name>

# Search
osiris find "<query>" --ns <ns> [--filter k=v,...] [--topk N] [--json]

# Statistics
osiris stats [--ns <ns>]

What's Next?

• Read the Examples for more use cases
• Check the README for detailed documentation
• Review the MVP Spec to understand the architecture
• Explore the source code to see how it works

Troubleshooting

"Connection refused"

Make sure HeroDB is running on port 6379:

redis-cli -p 6379 PING

"Namespace not found"

Create the namespace first:

osiris ns create <namespace>

"Config file not found"

Run osiris init first:

osiris init --herodb redis://localhost:6379

Need Help?

• Check the EXAMPLES.md for detailed usage patterns
• Review the README.md for architecture details
• Look at the docs/specs/osiris-mvp.md for the full specification

Happy organizing! 🚀