@orbitneststudio/cli

The command-line interface for the OrbitNest platform.

orbitnest brings the day-to-day backend workflow into your terminal and your repo: sign in once, link a directory to a project, run versioned SQL migrations, and generate TypeScript types straight from your live schema — the same ergonomics you expect from a modern backend toolchain.

npm install -g @orbitneststudio/cli
# or run without installing:
npx @orbitneststudio/cli --help

Requires Node.js 18+.

---

Quick start

# 1. Sign in (credentials are stored in ~/.orbitnest/credentials.json, mode 0600)
orbitnest login

# 2. Link the current directory to one of your projects
orbitnest link my-project        # by slug, name, or id
#   → writes .orbitnest/config.json (safe to commit)

# 3. Scaffold and apply a migration
orbitnest migration new "create posts table"
#   → edits migrations/001_create_posts_table.sql
orbitnest db push

# 4. Generate types from the live schema
orbitnest gen types              # → orbitnest.types.ts

---

Commands

Auth

Command	Description
orbitnest login	Sign in. Reads --email / --password, then ORBITNEST_EMAIL / ORBITNEST_PASSWORD, then prompts interactively (password input is masked).
orbitnest logout	Revoke the refresh token and clear the local session.
orbitnest whoami	Show the current session, API URL, and token expiry.

Projects

Command	Description
orbitnest projects	List your projects (name, slug, id).
orbitnest link [id|slug|name]	Link the current directory to a project. With no argument and a single project, links it automatically; otherwise lists choices. Writes .orbitnest/config.json.

Database & migrations

Command	Description
orbitnest migration new <name>	Scaffold migrations/NNN_<name>.sql with up / -- migrate:down sections.
orbitnest db push	Apply every pending migration in order, inside a transaction each.
orbitnest db status	Show which migrations are applied, pending, or modified-after-apply.
orbitnest db rollback [id]	Roll back the latest applied migration (or a specific id) using its -- migrate:down section.
orbitnest db reset --yes	Destructive. Drop every table in the project (internal auth_* tables are spared) and re-apply all migrations from scratch. Requires --yes.
orbitnest db sql "<SQL>"	Run ad-hoc SQL against the linked project. --file <path> runs a file.
orbitnest db connect	Print the direct Postgres connection string (when the deployment has direct connections enabled).
orbitnest gen types	Introspect the schema and emit TypeScript interfaces + a Database map. --out <file> (default orbitnest.types.ts) or --stdout.

Integrations

Command	Description
orbitnest webhooks list	List the project's webhooks.
orbitnest webhooks create --url <u> [--events INSERT,UPDATE,DELETE] [--table <t>] [--name <n>]	Create a webhook (prints the signing secret once).
orbitnest webhooks delete <id> / test <id>	Remove a webhook / send it a test event.
orbitnest sms get	Show the project's Twilio/SMS config.
orbitnest sms set [--sid <s>] [--token <t>] [--from <n>] [--enable|--disable]	Configure Twilio (auth token stored encrypted).
orbitnest sms test <phone>	Send a test SMS.

Options

Option	Applies to	Description
-p, --project <id|slug>	db / gen	Target a specific project, overriding the linked one.
-d, --dir <path>	migration / db	Migrations directory (default migrations).
-o, --out <file>	gen types	Output file.
--stdout	gen types	Print to stdout instead of a file.
-f, --file <path>	db sql	Read SQL from a file.
--url <url>	login	API base URL (default https://api.orbitnest.io).
-h, --help	—	Show help.
-v, --version	—	Show version.

---

Migrations

A migration is a plain .sql file named NNN_description.sql. The numeric prefix defines apply order. An optional -- migrate:down line splits the file into a forward (up) section and a rollback (down) section:

-- Migration 001: create posts table
-- Forward (up) SQL — applied by `orbitnest db push`.
CREATE TABLE posts (
  id   uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  title text NOT NULL,
  created_at timestamptz DEFAULT now()
);

-- migrate:down
-- Rollback SQL — applied by `orbitnest db rollback`.
DROP TABLE posts;

How it works:

• A migrations registry table tracks migration_id, name, checksum, executed_at, and status.
• Each migration runs wrapped in BEGIN; … COMMIT; — a failure rolls the whole file back and is recorded as failed.
• Already-applied migrations are skipped. If an applied file's checksum no longer matches, db push refuses to continue (add a new migration instead of editing history).

---

Type generation

orbitnest gen types reads information_schema.columns for your public schema (skipping internal auth_*, pg_*, and _* tables) and emits a strongly-typed module:

// Generated by @orbitneststudio/cli — do not edit by hand.
export interface Posts {
  id: string;
  title: string;
  created_at?: string | null;
}

export interface Database {
  "posts": Posts;
}

Re-run it after every schema change and commit the output, or wire it into a predev / prebuild script.

---

Configuration & files

Path	Scope	Contents
~/.orbitnest/credentials.json	global, 0600	Access/refresh tokens, API URL, user. Shared with the OrbitNest MCP server.
./.orbitnest/config.json	per-directory	Linked projectId, slug, name. Safe to commit.

Environment variables (override stored values):

• ORBITNEST_API_URL — API base URL.
• ORBITNEST_EMAIL, ORBITNEST_PASSWORD — non-interactive login.
• NO_COLOR — disable ANSI colors.

---

Development

npm install
npm run build      # bundle to dist/ with tsup (CJS + shebang)
npm run dev        # watch mode
npm run typecheck  # tsc --noEmit

node dist/index.js --help

---

License

MIT © OrbitNest