Guide

The layerbase CLI

layerbase is the official command-line tool for your cloud account. Sign in through your browser, list your databases, and connect with the right native client without ever pasting a connection string into your shell history. It also bridges to spindb, the open-source local database manager, so one tool covers both cloud and local work.

Install

Install it globally with your package manager of choice. You need Node.js 20 or newer.

install

npm i -g layerbase
# or: pnpm add -g layerbase
# or: bun add -g layerbase

This installs two commands, layerbase and a shorter lbase. For a two-letter lb, run layerbase alias. It only claims lb when nothing else on your system owns it (for example Debian's live-build ships an lb); if it is taken, the CLI leaves it alone and suggests a shell alias instead.

Quick start

quick start

layerbase              # open the interactive menu
layerbase login        # sign in through your browser
layerbase ls           # list your cloud databases
layerbase psql my-db   # connect with the right client, no password typed

Run layerbase with no command for an arrow-key menu that lets you sign in, list databases, connect, and drop into spindb. The menu is sugar over the commands below, so everything stays scriptable.

Sign in

layerbase login opens your browser, you sign in with GitHub or Google, and a 30-day token is returned to a loopback server the CLI runs on 127.0.0.1. A state nonce ties the response to your login, and the token is only ever delivered to a loopback address. It is stored at ~/.layerbase-cli/credentials.json with file mode 0600. This mirrors how the Layerbase desktop app signs in. Run layerbase logout to remove it, or layerbase whoami to see the account and token expiry.

Commands

layerbase login / logout / whoami

Sign in through the browser, sign out and remove the stored token, or show the signed-in account and token expiry. Add --json to whoami for scripting.

layerbase ls

List your cloud databases. Add --json to get machine-readable output for scripts.

layerbase connect <db>

Connect with the engine's native client. <db> accepts a database id or its name. Add --print to show the connection details instead of launching a client.

layerbase psql / mysql / redis-cli <db>

Shortcuts that connect to a Postgres-family, MySQL-family, or Redis/Valkey database with the matching client.

layerbase connection-string <db>

Print the full connection string, which reveals the password. Use this for engines without a dedicated connect shortcut.

layerbase clone <db> [local-name]

Create and populate a matching local spindb container from a cloud database. Defaults the local name to the cloud database name.

layerbase spindb [args...]

Run the local spindb CLI, passing arguments straight through. Local spindb commands need no login.

layerbase alias

Set up the short lb command, only if it is free on your system.

Connecting without leaking a password

Passing a connection string like psql "postgresql://..." leaks the password into your shell history, into ps while the client runs, and into terminal scrollback. The connect commands resolve the database over TLS and hand the credential to the client through an environment variable or a transient 0600 file that is deleted on exit. The password is never an argv value.

Postgres family

Passed via a PGPASSFILE temp 0600 file, deleted on exit.

MySQL / MariaDB

Passed via a --defaults-extra-file temp 0600 file, deleted on exit.

Redis / Valkey

Passed via the REDISCLI_AUTH environment variable.

Other engines

Use layerbase connection-string, or connect --print, and copy the value.

The connect, psql, mysql, and redis-cli commands need the matching native client (psql, mysql, redis-cli) on your PATH.

Clone a cloud database locally

layerbase clone copies a cloud database into a local spindb container so you can work against a real copy of your data offline. The CLI resolves the remote connection details (authenticated), spindb creates a matching container for the engine and version if it does not already exist, starts it, and pulls the data in. The remote password is passed to spindb through an environment variable, never on the command line.

clone

layerbase clone my-db            # into a container named "my-db"
layerbase clone my-db local-copy # into a container you name

The spindb bridge

spindb is the open-source tool that manages local database containers, and layerbase wraps the cloud account layer around it. Anything you pass after layerbase spindb runs spindb directly. It is found on your PATH, or run through npx / pnpx / bunx if it is not installed. Local spindb commands need no login.

spindb

layerbase spindb                  # open spindb's own menu
layerbase spindb create postgres  # run any spindb command locally

Scripting

Every menu action maps to a plain command, so the CLI works the same in a script as it does interactively. Add --json to ls and whoami for machine-readable output, and --print to connect to get connection details without launching a client. The CLI wraps the same public /v1 REST API the dashboard uses.

Configuration

Set LAYERBASE_API_URL to override the API base (default https://layerbase.com). You do not normally need this.

Connecting to a database REST API Desktop app Open your dashboard