Install the CLI

First, install the CLI globally on your machine:

npm install -g axiomdb-cli
axm -h

The CLI registers axm as a shortcut command. You can also use the full axiom command if you prefer, which is kept around for backwards compatibility with automation scripts.

What the CLI does under the hood

The axm CLI is a fast, compiled Rust binary tailored for your operating system. When you execute a command, it:

1. Grabs your active session token from ~/.axiomdb/.
2. Prepares a secure HTTPS request to the gateway at api.axiomdb.squareexp.com.
3. Attaches your PASETO v4 token so we know who you are.
4. Queries the correct API endpoints.
5. Formally formats the database response to look nice in your terminal.

Check for updates

Check your version using:

axm --version

If you ever need to update, just run:

npm update -g axiomdb-cli

Sign In

Now, log in to your account:

axm login

This will automatically open your web browser to authenticate via Square IdP using OAuth2 PKCE (Proof Key for Code Exchange). It's a secure way to log in without needing to manage client secrets in your terminal.

How the login works

 PKCE Auth Flow 
========================================================================
  [axm CLI] ──► (1. Generate PKCE challenges & Start loopback)
     │
     ▼ (2. Launch Browser)
  [Browser] ──► (3. Redirect to Square IdP Auth Page)
     │
     ▼ (4. User logs in & grants access)
  [Square IdP] ──► (5. Redirects back to local CLI loopback with auth code)
     │
     ▼ (6. CLI exchanges code + PKCE verifier for keys)
  [AxiomDB Gateway] ──► (7. Validates & issues PASETO tokens)
     │
     ▼ (8. Session saved locally!)
  [🔒 Auth Complete]
========================================================================

Double-check your session

To make sure you are logged in, run:

axm whoami
axm -li

This checks your token details. Your login token is a secure PASETO v4 token that lasts for 15 minutes before requiring an auto-refresh (which works behind the scenes for up to 7 days).

Create a Project

Let's spin up your first project! Run this command:

axm projects create --name "Square Experience" --app-key square_experience --env main

Creating a project automatically provisions your main branch database:

• Project name: Square Experience
• Active branch: main
• Database created: sq_square_experience_main

What happens when you create a project

The gateway immediately enqueues a database job. Our worker engine (square-dbctl) grabs the job and:

1. Creates your Postgres database:

   CREATE DATABASE sq_square_experience_main;

2. Creates three dedicated database users:

   CREATE ROLE square_experience_main_owner WITH LOGIN PASSWORD '***' CREATEDB;
   CREATE ROLE square_experience_main_rw WITH LOGIN PASSWORD '***';
   CREATE ROLE square_experience_main_ro WITH LOGIN PASSWORD '***';

3. Assigns the proper database permissions:

   GRANT ALL PRIVILEGES ON DATABASE sq_square_experience_main TO square_experience_main_owner;
   GRANT CONNECT ON DATABASE sq_square_experience_main TO square_experience_main_rw;
   GRANT CONNECT ON DATABASE sq_square_experience_main TO square_experience_main_ro;

4. Configures PgBouncer connection pooling to allow the runtime role to connect.
5. Stores your credentials securely on your system in ~/.creds/zone.env.
6. Logs a project.created event for auditing.

What is the app-key?

The app-key is used to prefix your databases and roles. Make sure it is:

• Short: Keep it simple since it's going to be in all your database names.
• Lowercase: Postgres defaults all names to lowercase.
• Permanent: Once set, changing it is tricky since we have to rename database objects.

Set Your Active Project

To save yourself from typing your project ID on every command, set your active project:

axm projects list
axm projects use <project-id>

Now, branch commands will default to this project automatically:

axm branches list          # Uses your active project
axm branches urls --name main  # Uses your active project

If you haven't selected a project, the CLI will tell you:

No active project selected.
Run `axm projects use <project-id>` to set one.

Allowlist Your Device

AxiomDB blocks all outside traffic by default. You need to allowlist your current IP address to connect:

Open the Web Console, go to the Network page, click My IP, and click Save JSON. This allowlists your device:

{
  "policy": {
    "apply": false,
    "mode": "restricted"
  },
  "rules": [
    {
      "cidr": "203.0.113.10/32",
      "expires_in": "7d",
      "label": "My current IP",
      "ports": "both",
      "scope": "project"
    }
  ]
}

Alternatively, use the CLI:

axm network allow --current

Understanding Network Modes

• restricted: (Default) Most secure. Only allowlisted IPs can access the database ports.
• public_runtime: Anyone can connect to PgBouncer (6432), but only allowlisted IPs can connect directly to Postgres (5432). Great for serverless applications.
• public_all: Fully public. Only use temporarily for debugging.

Copy Connection URLs

To get your database connection strings, run:

axm branches urls --name main

This returns the environment variables ready to copy into your .env file:

DATABASE_URL="postgresql://square_experience_rw:***@db.squareexp.com:6432/sq_square_experience_main?sslmode=require"
DIRECT_URL="postgresql://square_experience_owner:***@db.squareexp.com:5432/sq_square_experience_main?sslmode=require"

URL Anatomy Breakdown

Here is what these connection URLs mean:

⚡ Connection URL Anatomy ⚡
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  [Host: db.squareexp.com] ─────► The address of your database gateway.
  [Port 6432 vs 5432] ──────────► 6432 uses PgBouncer pooling; 5432 is direct Postgres.
  [Role: _rw vs _owner] ────────► _rw is for running queries; _owner is for schema migrations.
  [Database: sq_...] ───────────► The name of your database branch.
  [SSL: sslmode=require] ───────► Enforces secure, encrypted connections.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Copying via the Web Console

1. Open the Web Console and head to your project.
2. Click the Branches tab.
3. Click Connect on the main branch.
4. Select your preferred framework (Prisma, Drizzle, Kysely, etc.) to view pre-formatted copy-paste blocks.

Run a Migration

Copy both URLs into your local .env file:

DATABASE_URL="postgresql://square_experience_rw:***@db.squareexp.com:6432/sq_square_experience_main?sslmode=require"
DIRECT_URL="postgresql://square_experience_owner:***@db.squareexp.com:5432/sq_square_experience_main?sslmode=require"

Configure your Prisma schema file (schema.prisma) to use both:

datasource db {
  provider  = "postgresql"
  url       = env("DATABASE_URL")
  directUrl = env("DIRECT_URL")
}

Now, run your first database migration:

npx prisma migrate dev --name init

Prisma automatically uses DIRECT_URL (direct port 5432 with administrative owner rights) to run schema updates and manage migration tables, while using DATABASE_URL (pooled port 6432 with restricted read-write rights) for your normal application queries.

Why do I need two URLs?

Prisma Migrate needs direct access to Postgres for:

1. Shadow Databases: Creating temporary databases to verify your migration states (the standard runtime user cannot do this).
2. Advisory Locks: Preventing concurrent migrations from clashing (PgBouncer's transaction mode doesn't support this).

By separating the runtime role (_rw) from the migration role (_owner), we secure your database—even if your application credentials get compromised, your database schema cannot be altered or dropped.

Verify the Setup

Once your migration is complete, double-check that everything is connected:

# Check if migration tables were created
npx prisma migrate status

# Generate your local Prisma client
npx prisma generate

Check via the Web Console

Go to the Tables tab in your project dashboard. You should see your migrated tables! You can click on any table to view columns and browse rows.

Check via the CLI

axm monitoring summary

This prints out database size, connection counts, and migration status for your project.

Create a Branch for Feature Work

Now you can test schema migrations safely without affecting your production databases! Let's create a development branch:

axm branches create --name feature-auth --source main --lifespan 7d

This creates:

• A new database: sq_square_experience_main_br_feature-auth
• Separate credentials (a brand new owner role and read-write role)
• A clean schema copy from the main branch

Grab your feature branch URLs:

axm branches urls --name feature-auth

Put them in your .env file and run your migrations against the feature branch:

npx prisma migrate dev --name add-auth-tables

When you are done with development, you can merge your changes and delete the branch:

axm branches delete feature-auth