spindb

A CLI database toolbox: provision PostgreSQL, MongoDB, MySQL and Redis instances as containers (Podman first, Docker fallback), manage their lifecycle, browse their data in a full-screen terminal dashboard, and export connection strings for your projects.

Requirements

• Bun ≥ 1.4
• Podman or Docker on your PATH

Install

bun install

Optionally make the spindb binary available globally (symlinks src/index.ts into your global bin — no publishing involved):

bun run link     # or: bun run unlink to remove it
spindb --help

Quick start

spindb                              # open the dashboard (interactive terminal)
spindb provision postgres my-db     # create + start a PostgreSQL container
spindb list                         # show every instance
spindb env my-db                    # print shell exports for your project
spindb crud my-db                   # interactive table browser / CRUD loop
spindb stop my-db
spindb --gc                         # clean up every stopped instance

During development, swap spindb for bun src/index.ts (or bun run dev).

Dashboard

Bare spindb (or spindb ui) opens a three-tab terminal dashboard built on OpenTUI:

• Instances — list, inspect, start/stop/restart, remove, and provision instances; details pane shows credentials and the connection string
• Browse — pick a table/collection, page through records, filter (column=value), inspect the schema
• Logs — scrollable container log tail

| Key | Action | |---|---| | 1 / 2 / 3, tab | Switch tabs | | ↑↓ / j / k, enter | Navigate / inspect | | s / shift+s / r | Start / stop / restart instance | | b / l | Open browse / logs for the selected instance | | c | Copy connection string to the clipboard | | n / d | Provision / remove an instance | | f / d / [ ] (Browse) | Filter / toggle schema / page records | | ? | Keyboard help | | q, ctrl+c | Quit |

spindb ui --refresh 5 auto-refreshes instance state every 5 seconds. Without a TTY (pipes, CI) the dashboard refuses to start and suggests the scriptable subcommands instead.

Command reference

spindb                                   Open the dashboard (help when piped)
spindb ui [--refresh <s>]                Open the dashboard

spindb provision <type> <name> [flags]   Create a container (or file) instance
    --project <name>  --port <n>  --username <u>  --password <p>
    --database <db>  --image <img>  --label <k=v>
    --no-start  --no-wait  --json
spindb start|stop|restart <name>         Lifecycle (stop is graceful, 10s)
spindb remove <name> [--volumes] [--force] [--json]   Graceful stop + remove (--force kills)
spindb list [--project] [--status] [--type] [--json]
spindb inspect <name> [--json]           Full instance + container details
spindb connect <name> [--format url|env|shell|json]
spindb env <name> [--format env|url]     Shell exports (default: env)
spindb crud <name> [--table t] [--sql q] Interactive CRUD, or run one query
spindb shell <name> [-- args]       Open psql/mongosh/mysql/redis-cli
spindb backup <name> [--output f]   Dump to a file (sql/archive/rdb/db)
spindb restore <name> <file> --force Restore from a backup (overwrites data)
spindb doctor [--json]              Check engine, ports, containers, data dirs
spindb log <name> [--tail 100]           Container logs
spindb engine                            Report the detected engine
spindb upgrade                           Install the latest published version
spindb version | help

Global flags:
  --help, -h        Show help
  --version, -v     Show version
  --gc              Remove stopped instances (add --volumes to delete data)

Types: postgres, mongodb, mysql, redis.

Project integration

eval "$(spindb env my-db --format env)"   # export DATABASE_URL, POSTGRES_*, …
# or
spindb connect my-db --format url         # just the URL

State

Everything lives under ~/.spindb/ (override with SPINDB_CONFIG_DIR):

• instances.json — instance metadata (atomic writes)
• volumes/ — per-instance data directories, kept on remove unless you pass --volumes

Development

bun run start        # run the CLI
bun run dev          # run with hot reload
bun run typecheck    # tsc --noEmit
bun test             # unit tests (parser, store, providers, engine)
bun run build        # single-file binary → dist/spindb
bun run release      # publish a patch release and commit the version bump
bun run release 1.0.0 # publish an explicitly chosen version

See SPEC.md for the architecture and implementation plan.