CLI reference

The isotope command manages the local server. It is a bash script with Windows equivalents (isotope.bat, isotope.ps1).

Commands #

Command	What it does
`isotope start`	Starts the server in the background and records the pid.
`isotope stop`	Stops the managed server.
`isotope restart`	Stop, start, then open the browser.
`isotope status`	Project path, port, version and configuration summary.
`isotope doctor`	Full dependency and configuration diagnostic.
`isotope logs`	Last 80 log lines, with secrets redacted.
`isotope open`	Opens `http://127.0.0.1:<port>`.
`isotope version`	Prints the installed version.
`isotope update`	Safe `git pull` of the tracked branch, then restart.
`isotope repair`	Re-runs dependency install and reinstalls the CLI.
`isotope setup`	Runs `setup.sh --no-start`.
`isotope reinstall-widgets`	Refreshes Termux home-screen shortcuts.

update stashes uncommitted workisotope update runs git pull. If your tree is dirty it stashes first, which moves your changes out of the working tree. Recover with git stash pop. Commit before updating if you have local modifications you care about.

State directory #

Runtime state lives in ~/.isotope, overridable with ISOTOPE_HOME:

project-path: Absolute path to the checkout the CLI manages.
isotope.pid: Process id of the running server.
port: Port the server was started on.
logs/server.log: Server output, including patch results.
logs/update.log: Output from isotope update.
logs/browser-errors.log: Errors posted by the browser boundary.

Environment overrides #

ISOTOPE_HOME: State directory. Defaults to ~/.isotope.
ISOTOPE_PROJECT_DIR: Checkout the CLI should manage.
ISOTOPE_BRANCH: Branch update pulls. Defaults to the current tracking branch.
PORT: Port for start.

Repository scripts #

Operational checks, all dependency-free:

Script	Purpose
`npm run docs:validate`	Validates documentation links, versions and required files.
`npm run schema:drift`	Fails if `isotope-complete.sql` drifts from the live schema.
`npm run sql:quotes`	Checks dollar-quoted SQL bodies are balanced.
`npm run test:auth-bridge`	Unit-tests the auth bridge in a VM sandbox.
`npm run test:runtime-glue`	Asserts script load order and cache headers against a running server.
`npm run security:verify`	Verifies RLS cannot recurse infinitely.
`npm run backup:validate`	Validates backup file integrity.

Database tooling #

Two separate programs, and which you want depends on what you already have. They are easy to confuse and the distinction matters: restore replays a tarball, and a tarball only exists if you already had a working backend, so it is no help at all to someone setting up for the first time.

You have	You want
No Supabase project	`./supabase.sh setup --create "my-isotope"`
An empty project	`./supabase.sh setup --ref <ref>`
A project, unsure if it is correct	`./supabase.sh check --ref <ref>` — read-only
A working project	`./backup.sh backup`
A snapshot, and somewhere to put it	`./backup.sh restore <tarball> --supabase-url=<target>`

`supabase.sh` — first-run setup

Command	Does
`setup --pat T --ref R`	Provisions an empty project: schema, storage, the signup trigger, verify, then writes `.env`.
`setup --pat T --create "name"`	Creates a free project, waits for its database, then provisions it. Prints a generated DB password once.
`check --pat T --ref R`	Read-only. 13 checks in four groups; each failure prints the fix. `--json` for machines.
`ui [--port N]`	Web console on `127.0.0.1:8000`.
`status` / `stop`	Progress and ETA of the detached job, or kill it.

setup writes no database rows — no users, no seed data, no files. It moves an existing .env to .env.old rather than overwriting it, carries over PORT, the AI keys and SESSION_SECRET, and takes --no-env to skip that entirely. Full detail in Supabase setup.

`backup.sh` — backup, restore, verify

Command	Does
`backup [--keep N] [--no-storage]`	Schema, every table, auth users and storage files into a timestamped tarball, then verifies it against the source.
`restore <tarball> --supabase-url=<target>`	Applies it to the target, verifies, then scaffolds `.env`. Add `--schema-only` for structure with no people.
`verify <tarball>`	Cross-checks a tarball against any project. Exit 1 on mismatch.
`info <tarball>`	Integrity and manifest summary. Touches no project.
`ui` / `status` / `stop`	Same detached-job front ends as `supabase.sh`.

restore now refuses to guess its target It used to fall through to .backup_env then .env — the files that hold production credentials. So ./backup.sh restore dump.tar.gz with no --supabase-url silently wrote 42 tables and 43 auth users into the live database. It now dies rather than infer. If you have the old habit, this is the one to unlearn: a restore is the single command that must never guess where it is pointing.

Jobs started from either tool run detached, with their state on disk in backups/.job.json. Closing the browser tab, or restarting the console, does not stop or lose a running job — and status works with no server running at all, because the console and the CLI are two front ends over the same files.