CLI

The daam-cli is the developer tool for connecting to databases through DAAM. It establishes secure encrypted tunnels, manages authentication, and exposes a local PostgreSQL port - no database credentials required.

Installation

Download the binary for your platform and add it to your PATH:

Linux

curl -sLO https://<release-url>/daam-cli-linux-amd64
chmod +x daam-cli-linux-amd64
sudo mv daam-cli-linux-amd64 /usr/local/bin/daam-cli

macOS

curl -sLO https://<release-url>/daam-cli-darwin-arm64
chmod +x daam-cli-darwin-arm64
sudo mv daam-cli-darwin-arm64 /usr/local/bin/daam-cli

Verify the installation:

$ daam-cli version
daam-cli v0.x.x

Authentication

Authentication uses a browser-based OAuth flow. The CLI opens your browser, you log in through your organization's identity provider (or email/password), and the CLI receives a token automatically.

Login

$ daam-cli login
Opening browser for authentication...
Login successful. Organization: acme-corp

If you belong to multiple organizations, the browser shows an organization selector. To skip the selector, specify the org directly:

$ daam-cli login --org acme-corp

To bypass the identity provider selection page and go directly to a specific provider:

$ daam-cli login --provider okta

Logout

# Log out of the current profile
$ daam-cli logout

# Log out of all organizations
$ daam-cli logout --all

Token Lifecycle

Sessions refresh automatically. If a session expires, the CLI prompts you to log in again. You don't need to manage tokens manually.

Connecting to a Database

The connect command establishes a secure tunnel and exposes a local PostgreSQL port. It runs in the foreground until you press Ctrl+C.

$ daam-cli connect production
Connected to production
Local port: 127.0.0.1:5432
Connection mode: direct

Press Ctrl+C to disconnect.

While the tunnel is active, connect with any PostgreSQL client:

psql -h 127.0.0.1 -p 5432

Flags

Connection Modes

The CLI automatically selects the fastest connection path. Results are cached so subsequent connections are instant.

• Direct - lowest latency, preferred when network conditions allow.
• Relay - used when NAT, corporate firewalls, or network policies block direct connectivity. End-to-end encrypted - the relay cannot decrypt traffic.

Auto-Reconnect

If the tunnel drops (network change, laptop sleep), the CLI automatically reconnects. Your local TCP listener stays open during reconnect, so client applications don't need to be restarted. If access has been revoked, reconnect fails and the CLI exits.

Disconnecting

To disconnect an active tunnel from another terminal:

$ daam-cli disconnect production
Disconnected from production.

Running Commands

The run command establishes a tunnel, sets PostgreSQL environment variables, runs your command, then tears down the tunnel - all in one step.

$ daam-cli run production -- pg_dump --schema-only
-- PostgreSQL database dump
CREATE TABLE users (
    id uuid PRIMARY KEY,
    email text NOT NULL,
    ...
);

The CLI automatically sets PostgreSQL environment variables for the spawned process. The CLI exits with the command's exit code.

• PGHOST, PGPORT, PGDATABASE, PGUSER, PGSSLMODE

Connection banners are printed to stderr so stdout can be piped.

# Pipe output safely - only pg_dump output goes to stdout
$ daam-cli run production -- pg_dump --schema-only > schema.sql

Quick psql

The psql command is shorthand for daam-cli run <database> -- psql. Pass additional psql flags after --:

# Interactive psql session
$ daam-cli psql production

# Run a single query
$ daam-cli psql production -- -c "SELECT count(*) FROM orders"

# Execute a SQL file
$ daam-cli psql production -- -f migration.sql

With no database argument, the CLI lists available databases from the local cache:

$ daam-cli psql
Available databases:
  production    (agent: online)
  staging       (agent: online)
  dev-orders    (agent: offline)

Listing Databases

View databases you have access to:

$ daam-cli databases
NAME            DISPLAY NAME      AGENT STATUS
production      Production DB     online
staging         Staging           online
dev-orders      Dev Orders        offline

This also refreshes the local database cache used for tab completion.

Connection Status

Check your active tunnel connections:

$ daam-cli status
PROFILE     DATABASE      LOCAL PORT    MODE
acme-corp   production    5432          direct
acme-corp   staging       5433          relay

# Show status across all profiles
$ daam-cli status --all

Profiles

Each organization login creates a profile, named after the organization slug. If you work across multiple organizations, you'll have multiple profiles.

$ daam-cli profile list
PROFILE       ORG              DEFAULT
acme-corp     Acme Corp        *
personal      Personal Org

# Set a different default profile
$ daam-cli profile set-default personal

Profile Selection Priority

When multiple profiles exist, the CLI selects one in this order:

1. --profile flag
2. --org flag (matches profile by org slug)
3. DAAM_PROFILE environment variable
4. default_profile in config file
5. Auto-select if only one profile exists
6. Interactive prompt (or error in non-interactive mode)

# Use a specific profile for a single command
$ daam-cli --profile personal connect dev-db

# Or use the org flag
$ daam-cli --org personal connect dev-db

# Or set the environment variable
$ export DAAM_PROFILE=personal
$ daam-cli connect dev-db

Organizations

List all organizations you're a member of:

$ daam-cli orgs
SLUG          NAME              ROLE
acme-corp     Acme Corp         admin
personal      Personal Org      member

Tab Completion

Generate shell completion scripts for your shell:

# Bash
$ daam-cli completion bash > /etc/bash_completion.d/daam-cli

# Zsh
$ daam-cli completion zsh > /usr/local/share/zsh/site-functions/_daam-cli

# Fish
$ daam-cli completion fish > ~/.config/fish/completions/daam-cli.fish

Database name completions read from a local cache - no network calls are made during tab completion. Run daam-cli databases to refresh the cache.

Configuration

The CLI stores all state under ~/.daam/. Most files are managed automatically.

All state is stored in the ~/.daam/ directory with restricted file permissions. Credentials and keys are auto-managed.

Config File

The config file at ~/.daam/config.yaml is optional. It supports these fields:

# Default profile to use when multiple exist
default_profile: acme-corp

# Fixed local ports per database (avoids random port assignment)
databases:
  production:
    local_port: 5432
  staging:
    local_port: 5433

Environment Variables

Global Flags

Multiple Databases

Each connect command runs as an independent process with its own tunnel and TCP listener. You can connect to multiple databases simultaneously by running multiple connect commands in separate terminals:

# Terminal 1
$ daam-cli connect production --port 5432

# Terminal 2
$ daam-cli connect staging --port 5433

Command Reference