CLI Reference

The Pulsabase CLI is your main tool for managing and deploying projects. It handles everything from authentication to schema migrations and deployments.

Installation

npm install -g @pulsabase/cli

Verify:

pulsabase --version

---

Authentication Commands

pulsabase login

Authenticate with your Pulsabase account. Opens a browser window using a secure OAuth2 PKCE flow — no password is stored locally.

pulsabase login

Your access and refresh tokens are saved to ~/.pulsabase/credentials.json (with strict 600 permissions). Tokens are automatically refreshed before they expire.

Options:

Flag	Default	Description
--idp-url <url>	http://localhost:4000	IDP URL (for self-hosted setups)
--auth-url <url>	http://localhost:8889	Auth service URL
--project-id <id>	—	Optionally scope the login to a specific project

---

pulsabase logout

Remove stored credentials and sign out.

pulsabase logout

---

pulsabase whoami

Display the currently authenticated user’s email and identity.

pulsabase whoami

---

Project Commands

pulsabase init

Initialize a new Pulsabase project in the current directory or link to an existing one.

pulsabase init
pulsabase init my-app   # Provide the project name directly

The interactive wizard will:

1. Ask you to create a new project or link to an existing one
2. Prompt for your API key (shown once on project creation)
3. Ask your preferred language (TypeScript, Dart, Swift, Kotlin)
4. Set up the models directory (default: src/models)
5. Optionally configure OAuth client credentials

Generated files:

• .pulsabase/config.json — local machine config (added to .gitignore automatically)
• src/config.ts — developer-facing config with URLs and API key

Caution

The .pulsabase/ directory contains your project’s API key. It is automatically added to your .gitignore. Never commit it.

---

pulsabase link

Shorthand to link an existing project interactively (without creating a new one).

pulsabase link

---

Schema Commands

pulsabase db:sync

Synchronize your local TypeScript models to the remote database schema. Pulsabase prioritizes safety: destructive changes (dropping a table or column) are blocked by default.

# Preview what SQL migrations will be generated (no changes applied)
pulsabase db:sync --dry-run

# Apply safe migrations to the database
pulsabase db:sync

# Apply ALL changes, including destructive ones (requires confirmation)
pulsabase db:sync --force

How it works:

1. Reads your TypeScript models from the configured modelsDir
2. Resolves dependency order (foreign key dependencies sorted topologically)
3. Sends the schema to the backend, which diffs against the current database
4. Reports a plan: safe changes (adding columns, tables, indexes) vs. unsafe changes (dropping or altering)
5. If --force is used, prompts for confirmation before applying destructive changes

Flags:

Flag	Description
--dry-run	Preview the migration plan without applying any changes
--force	Bypass safety checks and apply destructive changes. Interactive confirmation required.

Always run --dry-run before --force. Dropped columns cannot be recovered.

---

pulsabase db:pull

Pull the existing schema from the database and generate local model files. This is the code-first → pull direction: you build tables in the Dashboard, then pull them as typed models.

# Pull all tables into src/models/
pulsabase db:pull

# Overwrite local files without prompting
pulsabase db:pull --force

# Specify a custom output directory
pulsabase db:pull --output src/lib/models

# Only pull specific tables
pulsabase db:pull --tables 'users,posts,comments'

Note

db:pull will not overwrite locally modified files unless you use --force. It shows a prompt for each modified file.

---

pulsabase db:rollback

Revert the remote database schema to a previous version.

# Revert the most recent migration
pulsabase db:rollback

# Rollback to a specific historical version
pulsabase db:rollback --to 5

Note

db:rollback only changes the remote database state. After rolling back, run db:pull to re-generate your local models from the actual current database schema — this guarantees your code stays in sync with what’s in the database.

pulsabase db:rollback
pulsabase db:pull   # Re-generate local models from the rolled-back schema

---

Model Generator

pulsabase generate:model <ModelName>

Scaffold a new TypeScript model file with the correct decorator structure.

pulsabase generate:model Post
pulsabase generate:model Comment --table comments

This creates src/models/Post.ts (or the equivalent in your configured modelsDir) with:

• @primary ID column
• Common column decorators
• static schema: ModelSchema block with tableName

---

Deployment Commands

pulsabase deploy

Deploy your project — schema, RLS policies, edge functions, and static hosting — in a single command.

pulsabase deploy
pulsabase deploy --dir build    # Specify a custom build directory

Flag	Description
--dir <path>	Build output directory (default: dist)
--dry-run	Preview changes without applying
--force	Skip all confirmation prompts

---

Utility Commands

pulsabase status

Show the current authentication status and linked project information.

pulsabase status

pulsabase --version

Display the installed CLI version.

pulsabase --version

---

Configuration Files

The CLI uses two config files:

File	Scope	Contents
~/.pulsabase/credentials.json	Global (machine-wide)	OAuth tokens, IDP URL
.pulsabase/config.json	Per-project	Project ID, API key, language, models dir

Both are created automatically by pulsabase login and pulsabase init. Neither should be committed to version control.