{"id":46411,"library":"soul-cli","title":"Soul","description":"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.","status":"active","version":"0.8.2","language":"javascript","source_language":"en","source_url":"https://github.com/thevahidal/soul","tags":["javascript"],"install":[{"cmd":"npm install soul-cli","lang":"bash","label":"npm"},{"cmd":"yarn add soul-cli","lang":"bash","label":"yarn"},{"cmd":"pnpm add soul-cli","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Native SQLite binding; platform-native compilation required, often causes install errors on non-Docker environments.","package":"better-sqlite3","optional":false}],"imports":[],"quickstart":{"code":"# Install globally\nnpm install -g soul-cli\n\n# Start server (replace sqlite.db with your database file)\nsoul -d sqlite.db -p 8000\n\n# Test: list all tables\ncurl http://localhost:8000/api/tables\n\n# Insert a row (adjust table name)\ncurl -X POST http://localhost:8000/api/users \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\": \"Alice\", \"email\": \"alice@example.com\"}'\n\n# Query with filters\ncurl \"http://localhost:8000/api/users?name=Alice\"\n\n# WebSocket connection (example using wscat)\n# wscat -c ws://localhost:8000\n# Subscribe to table changes by sending: {\"type\": \"subscribe\", \"table\": \"users\"}\n# Received updates as JSON when rows change.\n\n# Auth mode (requires JWT secret)\nsoul -d foobar.db -a --ts=my-jwt-secret-here --iuu=john --iup=secret123\n\n# Login\necho '{\"username\":\"john\",\"password\":\"secret123\"}' | http POST :8000/api/auth/login\n","lang":"bash","description":"Installs Soul CLI, starts a REST+WebSocket server on a SQLite database, demonstrates CRUD and filtering, WebSocket subscription, and auth mode login."},"warnings":[{"fix":"Use Docker or install build-essential (apt) / Xcode Command Line Tools (macOS) / Visual Studio Build Tools (Windows).","message":"better-sqlite3 native compilation fails on systems without required build tools (Python, make, g++).","severity":"breaking","affected_versions":"all"},{"fix":"Use --rate-limit-enabled and consider HTTP caching or a reverse proxy for production rate limiting.","message":"Default rate limiting is disabled; when enabled, default limits are low (100 requests per minute per IP) and not configurable.","severity":"gotcha","affected_versions":"<=0.8.2"},{"fix":"Set environment variables directly or use a wrapper script.","message":"The --envpath option loads .env files but is not documented for which variables; only NODE_ENV and custom variables are loaded, not DB config.","severity":"deprecated","affected_versions":">=0.6.0"},{"fix":"Use REST API for complex queries; WebSocket only streams entire table changes.","message":"WebSocket subscription only supports 'subscribe' and 'unsubscribe' messages; no advanced filtering or pagination.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"search_vec":"'0.8.2':25 'altern':62 'api':15 'authentication/authorization':35 'automat':11 'cadenc':49 'code':67 'configur':42,65 'cor':41 'crud':28 'data':33 'databas':23 'declar':27 'definit':60 'differenti':51 'endpoint':18,29 'exist':21 'generat':12,68 'instant':52 'irregular':48 'javascript':69 'jwt':37 'key':50 'layer':55 'licens':46 'limit':39 'mit':45 'provid':26 'rate':38 'real':31 'real-tim':30 'realtim':8 'releas':43 'requir':64 'rest':6,14,53 'schema':59 'server':9 'soul':1,2 'sqlite':5,22,57 'stream':34 'time':32 'unlik':61 'version':24 'websocket':17,54 'without':58","created_at":"2026-06-07T12:59:47.330446+00:00","updated_at":"2026-06-07T12:59:47.330446+00:00","problems":[{"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.","cause":"better-sqlite3 not installed or failed to compile during npm install -g soul-cli.","error":"Error: Cannot find module 'better-sqlite3'"},{"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.","cause":"Global npm binaries not in PATH after installation.","error":"soul: command not found"},{"fix":"Kill the other process or use a different port: 'soul -d db.sqlite -p 8001'.","cause":"Port 8000 already in use by another process.","error":"Error: listen EADDRINUSE :::8000"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/thevahidal/soul#readme","github":"https://github.com/thevahidal/soul","docs":null,"changelog":null,"pypi":null,"npm":"soul-cli","openapi_spec":null,"status_page":null,"smithery":null,"categories":["database","devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}