CLI Reference
Install and use the AltBase CLI to manage organizations, projects, API keys, database schemas, and generate TypeScript types from your terminal.
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> |