Complete reference for the AxiomDB CLI — authentication, project management, branching, backups, monitoring, networking, secrets, and audit logging.

AxiomDB CLI (`axm`)

The axm command-line interface is the primary tool for managing AxiomDB projects, databases, branches, and infrastructure from your terminal. It is a Rust binary distributed via npm and authenticates through a browser-based OAuth 2.0 PKCE flow with Square IdP.

Installation

Install and update the axm CLI

Authentication

Projects

Create, list, and switch between projects

Branches

Database branching for development workflows

Backups

List and restore database backups

Monitoring

Real-time metrics and streaming

Network

IP allowlisting and public access modes

Dashboard

Open the web dashboard

Secrets

Generate cryptographically secure secrets

Audit

View audit trail of account activity

Installation

Install the AxiomDB CLI globally via npm:

npm install -g axiomdb-cli

Verify the installation:

axm --version

axm 1.4.2

Prerequisites

The CLI requires Node.js 18+ and a modern browser for the OAuth login flow. On Linux servers without a browser, use axm login --headless to authenticate via a device code.

Updating

npm update -g axiomdb-cli

Shell Completion

Enable shell completions for faster navigation:

# Bash
axm completion bash >> ~/.bashrc

# Zsh
axm completion zsh >> ~/.zshrc

# Fish
axm completion fish > ~/.config/fish/completions/axm.fish

Global Flags

Every axm command supports these global flags:

Flag	Short	Description
`--help`	`-h`	Show help for any command
`--version`	`-V`	Print the CLI version
`--verbose`	`-v`	Enable verbose logging output
`--json`	`-j`	Output results as JSON instead of formatted text
`--no-color`		Disable ANSI color output
`--profile`	`-p`	Use a named CLI profile (default: `default`)
`--config`	`-c`	Path to a custom config file

Authentication

The authentication subsystem manages your session with Square IdP. All commands that interact with AxiomDB services require a valid session.

Opens a browser window for OAuth 2.0 PKCE authentication with Square IdP. The CLI starts a local callback server, receives the authorization code, and exchanges it for tokens.

axm login

▸ Opening browser for authentication...
▸ Waiting for callback...
✔ Authenticated as ajmal.js@example.com
✔ Session saved to ~/.axm/credentials

Flags:

Flag	Description
`--headless`	Display a URL to open manually instead of launching a browser (for SSH / remote sessions)
`--force`	Re-authenticate even if a valid session exists
`--timeout <seconds>`	Override the default login timeout (default: 120s)

Token Storage

OAuth tokens are stored in ~/.axm/credentials with 0600 permissions. Never share this file or commit it to version control.

When running on a remote server or CI environment without a browser:

axm login --headless

▸ Open this URL in your browser:
  https://auth.square.com/authorize?client_id=...&code_challenge=...

▸ Waiting for authentication... (expires in 120s)

Interactive login mode that prompts for organization selection when you belong to multiple Square organizations.

axm -li

▸ Opening browser for authentication...
✔ Authenticated as ajmal.js@example.com

Select an organization:
  1. Square Inc (org_abc123)
  2. AxiomDB Team (org_def456)
▸ Enter number: 2
✔ Active organization set to AxiomDB Team

`axm whoami`

Displays the currently authenticated user and session metadata.

axm whoami

User:       ajmal.js@example.com
Org:        AxiomDB Team (org_def456)
Session:    2024-01-15T10:30:00Z
Expires:    2024-01-15T22:30:00Z

With JSON output:

axm whoami --json

{
  "user": {
    "email": "ajmal.js@example.com",
    "name": "Ajmal J S",
    "id": "usr_7f3a2b1c"
  },
  "organization": {
    "name": "AxiomDB Team",
    "id": "org_def456",
    "role": "admin"
  },
  "session": {
    "created_at": "2024-01-15T10:30:00Z",
    "expires_at": "2024-01-15T22:30:00Z",
    "scopes": ["db:read", "db:write", "admin:projects"]
  }
}

`axm logout`

Destroys the current session and removes stored credentials.

axm logout

✔ Logged out successfully
✔ Credentials cleared from ~/.axm/credentials

Projects

Projects are the top-level organizational unit in AxiomDB. Each project contains databases, branches, and access control policies.

`axm projects list`

Lists all projects in the active organization.

axm projects list

ID            Name              Environment   Status    Branches   Created
───────────── ───────────────── ───────────── ──────── ────────── ──────────────────
prj_abc123    my-saas-app       production    active   3          2024-01-10
prj_def456    staging-server    staging       active   5          2024-01-08
prj_ghi789    local-dev         development   active   8          2024-01-05

JSON output:

axm projects list --json

[
  {
    "id": "prj_abc123",
    "name": "my-saas-app",
    "environment": "production",
    "status": "active",
    "branch_count": 3,
    "created_at": "2024-01-10T14:00:00Z",
    "app_key": "app_sk_live_xxx"
  }
]

`axm projects create`

Creates a new project with the specified configuration.

axm projects create \
  --name "my-new-project" \
  --app-key app_sk_live_xxxxxxxxxxxx \
  --env production

✔ Project "my-new-project" created
  ID:          prj_xyz789
  Environment: production
  App Key:     app_sk_live_xxx...xxxx
  Branch:      main (default)

Flags:

Flag	Required	Description
`--name`	Yes	Human-readable project name (3–64 characters, alphanumeric + hyphens)
`--app-key`	Yes	Application key for authenticating database connections
`--env`	No	Target environment: `development`, `staging`, or `production` (default: `development`)
`--region`	No	Deployment region: `us-east-1`, `eu-west-1`, `ap-southeast-1` (default: `us-east-1`)
`--plan`	No	Billing plan: `free`, `pro`, `enterprise` (default: `free`)

`axm projects use`

Sets the active project for all subsequent commands in the current session.

axm projects use prj_abc123

✔ Active project set to "my-saas-app" (prj_abc123)

Project Context

The active project is stored locally and persists across sessions. Use axm projects current to verify which project is active before running destructive commands.

`axm projects current`

Displays the currently active project.

axm projects current

Active project: my-saas-app (prj_abc123)
  Environment:  production
  Region:       us-east-1
  Branches:     3

Branches

AxiomDB branches are isolated copies of your database schema and data. They enable safe development workflows where changes can be tested before merging to production.

`axm branches list`

Lists all branches for the active project.

axm branches list

Name        Source      Status    Lifespan    Created                Divergence
─────────── ─────────── ──────── ─────────── ────────────────────── ──────────
main        —           active    permanent   2024-01-10T14:00:00Z   —
feat/auth   main        active    7d          2024-01-14T09:00:00Z   +12 -3
fix/timeout main        active    3d          2024-01-15T11:00:00Z   +2 -0
tmp/debug   feat/auth   active    24h         2024-01-15T16:00:00Z   +0 -1

JSON output:

axm branches list --json

[
  {
    "name": "main",
    "source": null,
    "status": "active",
    "lifespan": "permanent",
    "created_at": "2024-01-10T14:00:00Z",
    "divergence": { "added": 0, "removed": 0 },
    "endpoint": "ep-main-abc123.us-east-1.aws.axiomdb.io"
  },
  {
    "name": "feat/auth",
    "source": "main",
    "status": "active",
    "lifespan": "7d",
    "created_at": "2024-01-14T09:00:00Z",
    "divergence": { "added": 12, "removed": 3 },
    "endpoint": "ep-featauth-def456.us-east-1.aws.axiomdb.io"
  }
]

`axm branches create`

Creates a new branch from a source branch. The new branch gets an isolated endpoint and a copy of the source branch's schema and data at the time of creation.

axm branches create \
  --name "feat/new-feature" \
  --source main \
  --lifespan 7d

✔ Branch "feat/new-feature" created
  Source:    main
  Lifespan:  7d (expires 2024-01-22T14:00:00Z)
  Endpoint:  ep-featnewfeature-ghi789.us-east-1.aws.axiomdb.io
  Schema:    14 tables copied from main
  Data:      2.3 MB copied (snapshot)

Flags:

Flag	Required	Description
`--name`	Yes	Branch name (lowercase, alphanumeric + hyphens, max 64 chars)
`--source`	No	Source branch to copy from (default: `main`)
`--lifespan`	No	Auto-delete after duration: `1h`, `24h`, `3d`, `7d`, `30d`, `permanent` (default: `7d`)
`--no-data`	No	Copy schema only, skip data copy (faster for large databases)
`--restore`	No	Restore from a backup point instead of a live branch

Branch Limits

Free plans allow up to 5 branches per project. Pro plans allow 25. Contact support for higher limits on enterprise plans.

`axm branches delete`

Deletes a branch and all its associated data. This action is irreversible.

axm branches delete feat/auth

⚠ This will permanently delete branch "feat/auth" and all its data.
▸ Type the branch name to confirm: feat/auth
✔ Branch "feat/auth" deleted
  Freed: 2.3 MB

Flags:

Flag	Description
`--force`	Skip the confirmation prompt (use in CI/CD)
`--yes`	Alias for `--force`

`axm branches urls`

Generates connection URLs for a specific branch.

axm branches urls --name feat/auth

Branch: feat/auth (prj_abc123)

  Direct URL (connection pooling):
    postgresql://user:pass@ep-featauth-def456.us-east-1.aws.axiomdb.io:5432/axiomdb?sslmode=require

  Session URL (persistent connections):
    postgresql://user:pass@ep-featauth-def456-session.us-east-1.aws.axiomdb.io:5432/axiomdb?sslmode=require

  Prisma format:
    DATABASE_URL="postgresql://user:pass@ep-featauth-def456.us-east-1.aws.axiomdb.io:5432/axiomdb?sslmode=require"
    DIRECT_URL="postgresql://user:pass@ep-featauth-def456-session.us-east-1.aws.axiomdb.io:5432/axiomdb?sslmode=require"

Short form:

axm -br -url --name feat/auth

`axm gen tk`

Generates a short-lived connection token for a branch. Tokens expire after 1 hour by default.

axm gen tk --branch feat/auth

✔ Token generated for branch "feat/auth"
  Token:     axiomdb_tk_live_xxxxxxxxxxxxxxxxxxxxxxxx
  Expires:   2024-01-15T17:00:00Z (1 hour)
  Scopes:    db:read, db:write
  Branch:    feat/auth
  Endpoint:  ep-featauth-def456.us-east-1.aws.axiomdb.io

Flags:

Flag	Description
`--branch`	Target branch (required)
`--ttl`	Token time-to-live: `15m`, `1h`, `4h`, `24h` (default: `1h`)
`--read-only`	Generate a read-only token

Backups

AxiomDB automatically creates continuous backups (WAL archiving) for all projects. You can list available backups and restore to any point in time within the retention window.

`axm backups list`

Lists available backup points for a project.

axm backups list prj_abc123

Project: my-saas-app (prj_abc123)
Retention: 14 days

Earliest PIT:  2024-01-01T00:00:00Z
Latest PIT:    2024-01-15T15:42:33Z

Timestamp                Type          Size      Status
──────────────────────── ───────────── ───────── ────────
2024-01-15T15:42:33Z     continuous    —         available
2024-01-15T12:00:00Z     scheduled     156 MB    available
2024-01-15T00:00:00Z     scheduled     154 MB    available
2024-01-14T12:00:00Z     scheduled     152 MB    available
2024-01-14T00:00:00Z     scheduled     150 MB    available

JSON output:

axm backups list prj_abc123 --json

{
  "project_id": "prj_abc123",
  "retention_days": 14,
  "earliest_pit": "2024-01-01T00:00:00Z",
  "latest_pit": "2024-01-15T15:42:33Z",
  "backups": [
    {
      "timestamp": "2024-01-15T15:42:33Z",
      "type": "continuous",
      "size_bytes": null,
      "status": "available"
    }
  ]
}

`axm backups restore`

Restores a project to a specific point in time. Creates a new branch with the restored data.

axm backups restore prj_abc123 \
  --point-in-time 2024-01-14T08:30:00Z

✔ Restore initiated
  Source:     my-saas-app (prj_abc123)
  PIT:        2024-01-14T08:30:00Z
  Target:     branch "restore-2024-01-14-0830" (created)
  ETA:        ~3 minutes
  Status:     restoring...

Flags:

Flag	Required	Description
`--point-in-time`	Yes	ISO 8601 timestamp to restore to
`--target-branch`	No	Restore into an existing branch instead of creating a new one
`--project-id`	No	Override the active project context

Restore Safety

Restoring to a point in time creates a new branch by default. Your current data is never overwritten. Use --target-branch only if you intentionally want to replace an existing branch's data.

Monitoring

Real-time monitoring for your AxiomDB databases. View connection counts, query throughput, latency percentiles, and resource utilization.

`axm monitoring summary`

Displays a snapshot of current database metrics.

axm monitoring summary

Project: my-saas-app (prj_abc123)
Branch:  main
Region:  us-east-1

Connections
  Active:     12 / 100
  Idle:       38
  Waiting:    0

Queries (last 5 min)
  Total:      14,832
  Avg Latency: 2.3 ms
  P99 Latency: 18.7 ms
  Errors:     3

Storage
  Database:   245 MB
  WAL:        12 MB
  Total:      257 MB / 10 GB

CPU:    12%
Memory: 340 MB / 1 GB

JSON output:

axm monitoring summary --json

{
  "project_id": "prj_abc123",
  "branch": "main",
  "timestamp": "2024-01-15T15:45:00Z",
  "connections": {
    "active": 12,
    "idle": 38,
    "max": 100,
    "waiting": 0
  },
  "queries": {
    "total": 14832,
    "avg_latency_ms": 2.3,
    "p99_latency_ms": 18.7,
    "errors": 3,
    "window": "5m"
  },
  "storage": {
    "database_bytes": 256901120,
    "wal_bytes": 12582912,
    "total_bytes": 269484032,
    "limit_bytes": 10737418240
  }
}

`axm monitoring stream`

Streams real-time metrics to the terminal. Updates every 2 seconds by default.

axm monitoring stream

[15:45:02] conn=12  qps=492  p50=1.2ms  p99=15.3ms  cpu=11%  mem=340MB
[15:45:04] conn=14  qps=501  p50=1.1ms  p99=14.8ms  cpu=12%  mem=342MB
[15:45:06] conn=13  qps=487  p50=1.3ms  p99=16.1ms  cpu=10%  mem=341MB
^C

Flags:

Flag	Description
`--interval <ms>`	Update interval in milliseconds (default: 2000)
`--branch`	Monitor a specific branch (default: active branch)
`--format`	Output format: `table`, `json-lines`

Network

Manage network access to your AxiomDB databases. Control IP allowlists, CIDR rules, and public access modes.

`axm network current-ip`

Displays your current public IP address.

axm network current-ip

Your current IP: 203.0.113.42

`axm network allow --current`

Adds your current IP to the allowlist. This is the fastest way to grant yourself access during development.

axm network allow --current

✔ Rule created
  IP:      203.0.113.42/32
  Ports:   5432
  Label:   "Auto-detected IP"
  ID:      rule_a1b2c3
  Expires: never

`axm network list`

Lists all network access rules.

axm network list

ID            CIDR              Ports    Label                  Expires
───────────── ───────────────── ──────── ────────────────────── ──────────────
rule_a1b2c3   203.0.113.42/32   5432     Auto-detected IP       never
rule_d4e5f6   10.0.0.0/8        5432     VPC CIDR               never
rule_g7h8i9   192.168.1.0/24    both     Office network         2024-02-15

`axm network allow`

Adds a custom CIDR rule to the allowlist.

axm network allow 10.0.0.0/8 --ports both --label "VPC CIDR"

✔ Rule created
  CIDR:    10.0.0.0/8
  Ports:   5432, 6432 (both)
  Label:   "VPC CIDR"
  ID:      rule_d4e5f6
  Expires: never

Flags:

Flag	Required	Description
`CIDR`	Yes	CIDR notation (e.g., `203.0.113.0/24`)
`--ports`	No	Allowed ports: `5432` (direct), `6432` (pooler), `both` (default: `5432`)
`--label`	No	Human-readable label for the rule
`--expires`	No	Expiration duration: `1h`, `24h`, `7d`, `30d`, `never` (default: `never`)
`--project`	No	Apply rule to a specific project (default: all projects)

`axm network revoke`

Removes a network access rule by its ID.

axm network revoke rule_a1b2c3

✔ Rule rule_a1b2c3 revoked
  IP 203.0.113.42/32 no longer has access

`axm network public-mode`

Controls the public accessibility of your database endpoints.

axm network public-mode restricted

✔ Public mode set to "restricted"
  Only IPs in the allowlist can connect.

Modes:

Mode	Description
`restricted`	Only allowlisted IPs can connect (most secure, default)
`public_runtime`	Runtime connections are public; management APIs remain restricted
`public_all`	All connections are public (not recommended for production)

Security Warning

Setting public_all exposes your database to the internet. Only use this for throwaway development instances. Always prefer restricted mode with explicit IP allowlisting.

Dashboard

Opens the AxiomDB web dashboard in your default browser.

axm dashboard

▸ Opening https://console.axiomdb.io/projects/prj_abc123...

Short form:

axm -da

Flags:

Flag	Description
`--project`	Open a specific project's dashboard
`--branch`	Open a specific branch's dashboard
`--page`	Navigate to a specific page: `overview`, `branches`, `backups`, `monitoring`, `settings`

Secrets

Generate cryptographically secure random secrets for use as application keys, JWT secrets, or encryption keys.

`axm secrets generate`

axm secrets generate --label "JWT_SECRET" --bytes 32

✔ Secret generated
  Label:    JWT_SECRET
  Bytes:    32 (256 bits)
  Entropy:  256 bits
  Format:   base64

  Value:    a3F8bG2xR9mN4pL7wT5yH1vC6jK0dS8uE3nA7fB9gQ4iO6xZ2rV5tY8mW1cD3hJ
  ⚠ This value will only be shown once. Store it securely.

Flags:

Flag	Required	Description
`--label`	Yes	Descriptive label for the secret
`--bytes`	No	Number of random bytes (default: 32, max: 128)
`--format`	No	Output format: `base64`, `hex`, `url-safe-base64` (default: `base64`)

Audit

View an audit trail of all actions performed on your AxiomDB account and projects.

`axm audit list`

axm audit list --limit 50

Timestamp                Actor              Action               Resource                    Details
──────────────────────── ────────────────── ──────────────────── ─────────────────────────── ────────────────
2024-01-15T15:45:00Z     ajmal.js@...       branch.create        feat/auth (prj_abc123)      source=main
2024-01-15T15:30:00Z     ajmal.js@...       project.create       my-new-project (prj_xyz)    env=production
2024-01-15T14:00:00Z     ci-bot@...         branch.delete        tmp/old-feature (prj_abc)   —
2024-01-15T12:00:00Z     ajmal.js@...       network.allow        203.0.113.42/32             ports=5432
2024-01-15T10:00:00Z     ajmal.js@...       backup.restore       prj_abc123                  pit=2024-01-14T08:00:00Z

JSON output:

axm audit list --limit 50 --json

[
  {
    "timestamp": "2024-01-15T15:45:00Z",
    "actor": {
      "email": "ajmal.js@example.com",
      "id": "usr_7f3a2b1c"
    },
    "action": "branch.create",
    "resource": {
      "type": "branch",
      "name": "feat/auth",
      "project_id": "prj_abc123"
    },
    "details": {
      "source": "main"
    },
    "ip": "203.0.113.42",
    "user_agent": "axm/1.4.2"
  }
]

Flags:

Flag	Description
`--limit`	Number of entries to return (default: 20, max: 200)
`--actor`	Filter by actor email
`--action`	Filter by action type (e.g., `branch.create`, `project.delete`)
`--since`	Only entries after this ISO 8601 timestamp
`--until`	Only entries before this ISO 8601 timestamp
`--project`	Filter by project ID

Configuration File

The CLI stores its configuration in ~/.axm/config.json:

{
  "active_project": "prj_abc123",
  "active_organization": "org_def456",
  "default_region": "us-east-1",
  "default_branch_lifespan": "7d",
  "output_format": "text",
  "auto_update_check": true,
  "profiles": {
    "default": {
      "email": "ajmal.js@example.com"
    },
    "work": {
      "email": "ajmal.js@company.com"
    }
  }
}

Multiple Profiles

Use the --profile flag to switch between accounts:

axm whoami --profile work
axm projects list --profile work

Exit Codes

The CLI uses standard exit codes for scripting:

Code	Meaning
`0`	Success
`1`	General error
`2`	Misuse (invalid flags or arguments)
`3`	Authentication error
`4`	Authorization error (insufficient permissions)
`5`	Resource not found
`6`	Rate limited
`10`	Network error

CI/CD Integration

Example GitHub Actions workflow using axm:

name: Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm install -g axiomdb-cli
      - run: echo "${{ secrets.AXM_CREDENTIALS }}" > ~/.axm/credentials
      - run: axm projects use prj_abc123
      - run: axm branches list --json
      - run: axm monitoring summary

CI Authentication

For CI environments, export your credentials file as a secret and restore it during the workflow. Never hardcode tokens in workflow files.

CLI Reference (axm)

Installation

Authentication

Projects

Branches

Backups

Monitoring

Network

Dashboard

Secrets

Audit

On this page