Command-Line Tools - SoliDB Documentation

Overview

SoliDB provides essential command-line tools for data management:

solidb-repl

Interactive Lua REPL for testing and debugging.

solidb scripts

Manage Lua scripts from IDE with folder-based conventions.

solidb-dump

Export databases and collections to JSONL format.

solidb-restore

Import data from JSONL dumps back into SoliDB.

solidb-fuse

Mount blob collections as a filesystem.

solidb-repl

Interactive Lua REPL for testing scripts, querying data, and debugging. Similar to irb (Ruby) or lua -i.

USAGE

solidb-repl [OPTIONS]

Options

Option	Description	Default
-s, --server	Server URL	http://localhost:6745
-d, --database	Database name	_system
-k, --api-key	API key for authentication	-

REPL Commands

Command	Description
.help	Show help
.exit	Quit the REPL
.clear	Clear screen
.db <name>	Switch database
.status	Show connection info
.reset	Reset session state

Features

Tab completion for all APIs
Command history (~/.solidb_history)
Multiline input (end with \)

Session state persistence
Colored/formatted output
Execution timing

Example Session

_system> x = 42
  (0.15ms)
_system> x + 1
43
  (0.12ms)
_system> db:collection("users"):count()
1234
  (0.45ms)
_system> crypto.uuid()
"f47ac10b-58cc-4372-a567-0e02b2c3d479"
  (0.08ms)
_system> .db myapp
  Switched to database: myapp
myapp> db:query("FOR u IN users LIMIT 3 RETURN u.name")
[
  "Alice",
  "Bob",
  "Charlie"
]
  (1.23ms)

solidb scripts

Manage Lua scripts for custom API endpoints from your IDE. Uses folder-based conventions to map file paths to API routes.

Folder Convention

scripts/
├── hello.lua                → /api/custom/{db}/hello
├── users.lua                → /api/custom/{db}/users
├── users/
│   └── _id.lua              → /api/custom/{db}/users/:id
└── api/
    └── v1/
        └── products.lua     → /api/custom/{db}/api/v1/products

Naming Rules: Filename (without .lua) = last API path segment. Prefix with _ for path parameters (e.g., _id.lua → :id).

Comment Header

Configure methods and metadata in the first lines of your Lua file:

-- @methods GET, POST
-- @description List or create users
-- @collection users

local users = db:collection("users")

if request.method == "GET" then
    return users:find({})
else
    return users:insert(request.body)
end

Directive	Required	Example	Description
@methods	No*	GET, POST, PUT	HTTP methods (comma-separated). Default: GET
@description	No	User CRUD endpoint	Human-readable description
@collection	No	users	Target collection for context
@ws	No	true	WebSocket endpoint (or use `@methods WS`)

Commands

init Initialize a scripts directory

solidb scripts init --host localhost --port 6745 --db mydb

Creates solidb-scripts.toml configuration file.

login Authenticate with the server

solidb scripts login -u admin

Prompts for password and saves JWT token to config.

push Push scripts to server

solidb scripts push # Push all scripts
solidb scripts push users.lua # Push single file
solidb scripts push users/ # Push directory

pull Pull scripts from server

solidb scripts pull # Pull all scripts
solidb scripts pull --force # Overwrite local files

watch Auto-sync on file changes

solidb scripts watch

Watches for file changes and automatically pushes updates to server.

list / diff / delete Other commands

solidb scripts list # List scripts on server
solidb scripts diff # Show diff between local and server
solidb scripts delete users/:id # Delete script by API path

Environment Variables

Set these in a .env file for CI/CD or automated workflows:

Variable	Description
SOLIDB_API_KEY	API key for authentication (takes precedence over login token)
SOLIDB_HOST	Override server host
SOLIDB_PORT	Override server port
SOLIDB_DATABASE	Override target database

Example Workflow

# 1. Initialize project
solidb scripts init --host localhost --port 6745 --db myapp

# 2. Authenticate (choose one method)
solidb scripts login -u admin            # Interactive login
echo "SOLIDB_API_KEY=xxx" > .env       # Or use API key

# 3. Create a script
cat > users.lua << 'EOF'
-- @methods GET, POST
-- @description User management
local users = db:collection("users")
if request.method == "GET" then
    return users:find({})
else
    return users:insert(request.body)
end
EOF

# 4. Push to server
solidb scripts push

# 5. Start watching for changes
solidb scripts watch

# 6. Edit in your IDE - changes auto-deploy!

solidb-dump

USAGE

solidb-dump [OPTIONS] --database <DATABASE>

Options

Option	Description	Default
-d, --database	Database name (required)	-
-c, --collection	Collection name	All
-o, --output	Output file	stdout
-H, --host	Database host	localhost
-P, --port	Database port	6745
-u, --user	Username	-
-p, --password	Password	-

Examples

Dump entire database

solidb-dump -d mydb -o backup.jsonl

Dump single collection to gzip

solidb-dump -d mydb -c users | gzip > users.jsonl.gz

Shard-Aware: queries all shards across all nodes for sharded collections, ensuring complete backups.

solidb-restore

USAGE

solidb-restore [OPTIONS] --input <FILE>

Options

Option	Description	Default
-i, --input	Input JSONL file (required)	-
--database	Override database name	From dump
--collection	Override collection name	From dump
--create-database	Create database if missing	false
--drop	Drop existing collections first	false

Examples

Restore and create db

solidb-restore -i backup.jsonl --create-database

Restore to different database

solidb-restore -i backup.jsonl --database newdb --create-database

solidb-fuse

USAGE

solidb-fuse [OPTIONS] --mount <MOUNT>

Options

Option	Description	Default
--mount	Mount point path (required)	-
-d, --daemon	Run as daemon	false
--pid-file	PID file	./solidb-fuse.pid
--log-file	Log file	./solidb-fuse.log

Examples

Mount to directory

mkdir ~/solidb-mount
solidb-fuse --mount ~/solidb-mount --password admin

Run as Daemon

solidb-fuse --mount /mnt/db -d --log-file /var/log/fuse.log

Supported Formats

JSONL (Recommended)

Restores a collection from a JSONL (or mixed JSONL/Binary) file. Automatically handles collection creation and data distribution.

{"_database":"mydb","_collection":"users","_id":"1","name":"Alice"}
{"_database":"mydb","_collection":"users","_id":"2","name":"Bob"}

JSON Array

Standard JSON array. Good for migrations.

[
{"name":"Alice"},
{"name":"Bob"}
]

CSV

Rows and columns. Requires --database and --collection flags.

name,age,active
Alice,30,true
Bob,25,false

Common Workflows

Daily Backups

# Automated daily backup script

DATE=$(date +%Y%m%d)

solidb-dump -d production -o "backups/prod-${DATE}.jsonl"

gzip "backups/prod-${DATE}.jsonl"

Environment Migration

# Export from production

solidb-dump -H prod.example.com -d mydb -o prod-export.jsonl

# Import to staging

solidb-restore -i prod-export.jsonl -H staging.local --create-database --drop

Clone Collection

# Dump specific collection

solidb-dump -d mydb -c users -o users.jsonl

# Restore as new collection

solidb-restore -i users.jsonl --collection users_backup

Selective Restore

# Filter with jq and restore

cat backup.jsonl | jq -c 'select(.status == "active")' > active-only.jsonl

solidb-restore -i active-only.jsonl --create-database