CLI Reference

Installation

npm install -g @altbasedb/cli

After installation the altbasedb command is available globally.

altbasedb --version
# 0.1.0

Authentication

Login

altbasedb login

You will be prompted for your email and password. On success the CLI persists an access token to ~/.atlas/config.json.

Email: you@example.com
Password: ********
✓ Logged in successfully

Logout

altbasedb logout

Clears the stored access token from the config file.

Project Initialization

Init

altbasedb init

Initializes a new project in the current directory by creating a .env.local file with your project's connection details. Prompts for API URL, organization, and project selection.

Organizations

List Organizations

altbasedb orgs list

Organizations:
───────��────────────────────────────────────────────────────
  My Startup  (free)  org_abc123
  Agency Co   (pro)   org_def456

Each row shows the organization name, tier, and ID.

Create an Organization

altbasedb orgs create "My New Org"

✓ Organization 'My New Org' created (org_ghi789)

Projects

Project commands require a current organization to be set in the config file.

List Projects

altbasedb projects list

Projects:
────────────────────��───────────────────────────────────────
  Production API  proj_aaa111
  Staging         proj_bbb222 ◀ current

The current marker indicates which project is active for key management commands.

Create a Project

altbasedb projects create "My App"

Creates the project under the current organization and automatically selects it as the active project.

✓ Project 'My App' created (proj_ccc333)

Delete a Project

altbasedb projects delete proj_aaa111

✓ Project proj_aaa111 deleted

This permanently removes the project, its tenant schema, and all associated data. It cannot be undone.

API Keys

Key commands operate on the currently selected project.

List Keys

altbasedb keys list

API Keys:
──────��───────────────────────────────────────────────────────────────
  anon-web     [anon]     sb_anon_abc1...  key_111
  backend-svc  [service]  sb_svc_def2...   key_222

Only the key prefix is shown. The raw key value is never displayed after creation.

Create a Key

altbasedb keys create "my-key" --role anon

Available roles: anon, service, custom.

✓ API key 'my-key' created [anon]
  Key: sb_anon_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  Save this key — it won't be shown again.

Store the raw key immediately. It is returned only once.

Delete a Key

altbasedb keys delete key_111

✓ API key key_111 deleted

Revoked keys are rejected by the gateway immediately.

Database Commands

Database commands operate on the currently selected project and require a service key.

Show Schema

altbasedb db schema

Displays the full database schema for the current project including tables, columns, types, constraints, and relationships.

List Tables

altbasedb db tables

Lists all tables in the current project's tenant schema.

Pull Schema as DDL

altbasedb db pull

Outputs the current schema as SQL DDL statements. Useful for version control or migration tracking.

Execute SQL

altbasedb db sql "SELECT count(*) FROM users WHERE active = true"

Executes a raw SQL query against the current project's tenant schema and prints the result as a formatted table.

TypeScript Type Generation

Generate Types

altbasedb gen types

Introspects the database schema and generates TypeScript type definitions for all tables. Output can be redirected to a file:

altbasedb gen types > src/types/database.ts

The generated types include interfaces for each table with correct column types, nullability, and default values.

Status

altbasedb status

Displays the current configuration and project details:

AltBaseDB Status:
─────��──────────────────────────────────
  API URL:     http://localhost:4000
  Org:         org_abc123
  Project:     proj_bbb222
  Name:        Staging
  Tier:        free

If no project is selected, project-specific fields display (none).

Configuration

The CLI stores all state in a single JSON file:

Path	Contents
~/.atlas/config.json	API URL, access token, current org ID, current project ID

Config File Format

{
  "api_url": "http://localhost:4000",
  "access_token": "eyJhbGci...",
  "current_org": "org_abc123",
  "current_project": "proj_bbb222"
}

When no config file exists, the CLI defaults api_url to http://localhost:4000.

Environment Variable Overrides

You can override config values with environment variables:

ATLAS_API_URL=https://api.yourapp.com altbasedb status

Switching Context

Edit ~/.atlas/config.json directly to point at a different org, project, or API URL:

{
  "api_url": "https://api.yourapp.com",
  "current_org": "org_def456",
  "current_project": "proj_xyz789"
}

Command Summary

Command	Description
altbasedb init	Initialize project (creates .env.local)
altbasedb login	Authenticate with email and password
altbasedb logout	Clear stored credentials
altbasedb orgs list	List your organizations
altbasedb orgs create <name>	Create an organization
altbasedb projects list	List projects in the current org
altbasedb projects create <name>	Create a project and select it
altbasedb projects delete <id>	Permanently delete a project
altbasedb keys list	List API keys for the current project
altbasedb keys create <name> [--role]	Create an API key (default role: anon)
altbasedb keys delete <id>	Revoke an API key
altbasedb db schema	Show database schema
altbasedb db tables	List all tables
altbasedb db pull	Pull schema as SQL DDL
altbasedb db sql "..."	Execute a SQL query
altbasedb gen types	Generate TypeScript types from schema
altbasedb status	Show connection and project info
altbasedb --help	Print help text
altbasedb --version	Print CLI version

Error Messages

The CLI provides clear messages when context is missing:

Situation	Message
Not logged in	Not logged in. Run: altbasedb login
No org selected	No organization selected. Set one first or pass --org
No project selected	No project selected.
API error	Error: <server message>