Dash CLI

The Sovereign Database for Your Command Line

Your data. Your device. Your rules. No cloud required.

Installation

# From npm (coming soon)
npm install -g @affectively/dash-cli

# Or run directly with bun
bun run bin/dash.ts

Quick Start

# Initialize a new Dash database
dash init

# Create a table and insert data
dash query "CREATE TABLE notes (id TEXT PRIMARY KEY, content TEXT, created_at INTEGER)"
dash query "INSERT INTO notes VALUES ('1', 'My first note', 1707321600000)"

# Query with SQL
dash query "SELECT * FROM notes"

# Pipe to JQ transformations
dash query "SELECT * FROM notes" | dash jq '.[].content'

Commands

| Command | Description | |---------|-------------| | dash init | Initialize a new Dash database in .dash/ | | dash query <sql> | Execute a SQL query | | dash search <text> | Semantic vector search | | dash sync | Sync with configured remotes (Relay, D1) | | dash export | Export database to various formats | | dash import | Import from external sources | | dash jq <expr> | JQ-style JSON transformation | | dash status | Show database and sync status | | dash bench | Run performance benchmarks | | dash help | Show help message |

Benchmarking

Dash includes built-in benchmarking that stores results in the local database - Dash measuring Dash.

Running Benchmarks

# Run with default 1000 iterations
dash bench

# Run with custom iterations
dash bench --iterations=5000

# Compare with previous runs
dash bench --compare

# View benchmark history
dash bench --history

Benchmark Results

Performance on Apple Silicon (M-series), Bun 1.3.5+:

| Operation | Ops/Sec | Avg Latency | Min Latency | Max Latency | |-----------|---------|-------------|-------------|-------------| | SELECT by ID | 117,222 | 0.0085 ms | 0.0040 ms | 0.1250 ms | | JSON.parse | 46,109 | 0.0217 ms | 0.0080 ms | 0.0830 ms | | INSERT | 3,446 | 0.2902 ms | 0.1250 ms | 0.5830 ms | | UPDATE | 3,372 | 0.2966 ms | 0.1250 ms | 0.6250 ms | | DELETE | 3,050 | 0.3279 ms | 0.1670 ms | 0.6670 ms |

Key Insights:

• Read operations (SELECT) are 34x faster than writes
• Bun's native SQLite achieves enterprise-grade performance
• Sub-millisecond latency for all operations
• Write operations bottlenecked by SQLite's WAL/fsync (expected)

Viewing Stored Results

Benchmark results are stored in the dash_benchmarks table:

# View all benchmark history
dash query "SELECT name, ops_per_sec, avg_latency_ms, created_at FROM dash_benchmarks ORDER BY created_at DESC"

# View by operation type
dash query "SELECT * FROM dash_benchmarks WHERE operation = 'select' ORDER BY created_at DESC LIMIT 5"

# Extract just ops/sec with jq
dash query "SELECT * FROM dash_benchmarks" | dash jq '.[] | {name: .name, ops: .ops_per_sec}'

Sync

One-Time Sync

# Sync specific tables with a relay
dash sync --relay=wss://relay.example.com --tables=notes,users

Seed Mode (Persistent Peer)

Run the CLI as a persistent sync peer for other devices:

# Run as seed peer (keeps running)
dash sync --relay=wss://relay.example.com --seed --tables=notes

This enables:

• Desktop CLI seeding mobile devices
• Server instances providing always-on sync
• Peer-to-peer sync without central servers

Configuration

Configure sync in .dash/config.json:

{
  "sync": {
    "relay": "wss://relay.example.com",
    "d1": "https://api.example.com/sync"
  }
}

JQ Transformations

Pipe query output through JQ-style transformations:

# Extract specific fields
dash query "SELECT * FROM users" | dash jq '.[].name'

# Filter and transform
dash query "SELECT * FROM scores" | dash jq '.[] | select(.score > 80)'

# Aggregate
dash query "SELECT * FROM numbers" | dash jq '[.[] | .value] | add'

# Sort
dash query "SELECT * FROM items" | dash jq 'sort_by(.created_at)'

Supported JQ Operations

• Path access: .field, .field.subfield, .[0], .[]
• Functions: length, keys, values, type, sort, sort_by(), reverse, unique, flatten, first, last, min, max, add
• Filtering: select(condition), map(expr)
• Conditionals: if-then-else
• Pipes: expr | expr | expr

Export & Import

Export

# Export to JSON file
dash export --to=json --file=backup.json

# Export to stdout
dash export --to=json

Import

# Import from JSON
dash import --from=json --file=data.json

# Firebase (export first, then import)
dash import --from=firebase --project=my-app

# Notion
dash import --from=notion --token=secret_xxx

Database Location

By default, Dash stores data in .dash/ in the current directory.

# Change location with environment variable
DASH_DIR=/path/to/custom dash init

Schema

Core tables created by dash init:

| Table | Purpose | |-------|---------| | dash_meta | Database metadata (version, config) | | dash_sync_queue | Pending sync operations | | dash_vectors | Vector embeddings for semantic search | | dash_yjs_state | CRDT state for sync | | dash_benchmarks | Performance benchmark history | | dash_ucans | UCAN authentication tokens |

The Pirate's Creed

We don't ask permission to own our data.
We don't pay rent to access our memories.
We don't need their servers to collaborate.

Your data. Your device. Your rules.

License

MIT - Use freely, own your data.

Links

• Dash Core (Browser)
• Affectively