soul-cli

library0.8.2jsnpmunverified

Soul is a SQLite REST and Realtime server that automatically generates a REST API and WebSocket endpoint for any existing SQLite database. Version 0.8.2 provides declarative CRUD endpoints, real-time data streaming, authentication/authorization with JWT, rate limiting, and CORS configuration. Released under MIT license with irregular cadence. Key differentiator: instant REST+WebSocket layer over SQLite without schema definition, unlike alternatives that require configuration or code generation.

database devops

npm install soul-cli

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SOUL-CLI

soul-cli

databasejavascriptv0.8.2

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Installs Soul CLI, starts a REST+WebSocket server on a SQLite database, demonstrates CRUD and filtering, WebSocket subscription, and auth mode login.

# Install globally npm install -g soul-cli # Start server (replace sqlite.db with your database file) soul -d sqlite.db -p 8000 # Test: list all tables curl http://localhost:8000/api/tables # Insert a row (adjust table name) curl -X POST http://localhost:8000/api/users \ -H "Content-Type: application/json" \ -d '{"name": "Alice", "email": "alice@example.com"}' # Query with filters curl "http://localhost:8000/api/users?name=Alice" # WebSocket connection (example using wscat) # wscat -c ws://localhost:8000 # Subscribe to table changes by sending: {"type": "subscribe", "table": "users"} # Received updates as JSON when rows change. # Auth mode (requires JWT secret) soul -d foobar.db -a --ts=my-jwt-secret-here --iuu=john --iup=secret123 # Login echo '{"username":"john","password":"secret123"}' | http POST :8000/api/auth/login

Debug

Known issues

breakingbetter-sqlite3 native compilation fails on systems without required build tools (Python, make, g++).

fix

Use Docker or install build-essential (apt) / Xcode Command Line Tools (macOS) / Visual Studio Build Tools (Windows).

affects: all

gotchaDefault rate limiting is disabled; when enabled, default limits are low (100 requests per minute per IP) and not configurable.

fix

Use --rate-limit-enabled and consider HTTP caching or a reverse proxy for production rate limiting.

affects: <=0.8.2

deprecatedThe --envpath option loads .env files but is not documented for which variables; only NODE_ENV and custom variables are loaded, not DB config.

fix

Set environment variables directly or use a wrapper script.

affects: >=0.6.0

gotchaWebSocket subscription only supports 'subscribe' and 'unsubscribe' messages; no advanced filtering or pagination.

fix

Use REST API for complex queries; WebSocket only streams entire table changes.

affects: all

Errors

Common errors & fixes

Error: Cannot find module 'better-sqlite3'

better-sqlite3 not installed or failed to compile during npm install -g soul-cli.

fix

Ensure build tools are installed (e.g., 'sudo apt install python3 make g++' on Debian/Ubuntu) and reinstall: 'npm install -g soul-cli'. Alternatively, use the Docker image.

soul: command not found

Global npm binaries not in PATH after installation.

fix

Check npm global prefix with 'npm config get prefix' and add its bin directory to PATH. Common on Windows: %APPDATA%\npm. On Unix: /usr/local/bin or ~/.npm-global/bin.

Error: listen EADDRINUSE :::8000

Port 8000 already in use by another process.

fix

Kill the other process or use a different port: 'soul -d db.sqlite -p 8001'.

Upgrade

Version history

0.8.2latest on npm

Audit

Dependencies

better-sqlite3requiredNative SQLite binding; platform-native compilation required, often causes install errors on non-Docker environments.

Agent activity

28 hits · last 30 days

node

Resources

githubhttps://github.com/thevahidal/soul ↗

packagesoul-cli ↗

homepagehttps://github.com/thevahidal/soul#readme ↗