oracle-cli

Standalone command-line interface for Oracle knowledge base.

Pure HTTP client — no server internals, no database access. Talks to the Oracle server over localhost.

Usage

No install needed — run directly from GitHub:

bunx github:Soul-Brews-Studio/oracle-cli <command>

Prerequisites

Oracle server must be running. Start it with:

oracle-cli server start

This spawns oracle-v2 in the background. You need oracle-v2 installed or available via bunx.

Commands

Knowledge Base

oracle-cli search <query>           # Search (hybrid, fts, or vector)
oracle-cli search "patterns" -l 5   # Limit results
oracle-cli search "vault" -m fts    # FTS-only mode
oracle-cli search "auth" -p myproj  # Filter by project

oracle-cli learn -p "lesson text"   # Add a learning
oracle-cli learn -p "lesson" -c "tag1,tag2" --origin human

oracle-cli list                     # List documents
oracle-cli list -t learning -l 20   # Filter by type

oracle-cli stats                    # Knowledge base statistics

Threads

oracle-cli threads                  # List threads
oracle-cli threads -s open          # Open threads only
oracle-cli thread <id>              # View thread + messages

Schedule

oracle-cli schedule                 # List upcoming events
oracle-cli schedule list -d 2026-03-05
oracle-cli schedule add -d 2026-03-10 -e "Meeting" -t 14:00

Traces & Inbox

oracle-cli traces                   # List discovery traces
oracle-cli trace <id>               # View a trace
oracle-cli inbox                    # View handoff inbox

Server Management

oracle-cli server status            # Check if running
oracle-cli server start             # Start oracle-v2 server
oracle-cli server stop              # Graceful HTTP shutdown

Vault

oracle-cli vault status             # Vault config & pending changes
oracle-cli vault sync               # Commit + push to GitHub
oracle-cli vault pull               # Pull vault files locally
oracle-cli vault init owner/repo    # Initialize vault
oracle-cli vault migrate --list     # Find repos with psi directories

Global Options

Every command supports --json for machine-readable output:

oracle-cli stats --json
oracle-cli search "query" --json
oracle-cli server status --json

Configuration

Environment Variable	Default	Description
ORACLE_URL	http://localhost:47778	Full server URL (takes priority)
ORACLE_PORT	47778	Server port (used when ORACLE_URL is not set)

Point to a remote Oracle server:

export ORACLE_URL=https://oracle.example.com
oracle-cli stats

Architecture

oracle-cli ──HTTP──> oracle-v2 server (:47778)
                         │
                    ┌────┴────┐
                    │ SQLite  │
                    │ + FTS5  │
                    │ + vec   │
                    └─────────┘

• 9 commands are pure HTTP (fetch against /api/*)
• server start spawns oracle-v2 via Bun.spawn(['bunx', 'oracle-v2', '--server'])
• vault * delegates to execSync('bunx oracle-v2 vault ...')

Quick Run (no install)

bunx github:Soul-Brews-Studio/oracle-cli stats
bunx github:Soul-Brews-Studio/oracle-cli search "patterns"

Development

ghq get -p Soul-Brews-Studio/oracle-cli
cd $(ghq root)/github.com/Soul-Brews-Studio/oracle-cli
bun install
bun run src/index.ts --help
bun run build   # type-check

License

MIT