Altertable CLI

The Altertable CLI lets you manage Altertable from a terminal. Use it to query lakehouse data, load files, and automate workflows in scripts or CI.

Goal

Install the CLI, create an authenticated profile, verify access, and use commands for queries, ingestion, and automation.

Prerequisites

• An Altertable account with access to an organization and environment.
• A terminal that can run the installer, npm, or a downloaded binary.
• Lakehouse credentials for commands that query or ingest data.

Steps

1. Install the CLI

Install the CLI with the shell installer. This is the recommended path for most users:

Copy
curl -fsSL https://install.altertable.ai | sh

You can also install it from npm:

Copy
npm install -g @altertable/cli

Or download a prebuilt binary from GitHub Releases.

2. Sign in

Sign in with your browser:

Copy
altertable login

The login flow creates or reuses a local profile for the signed-in organization and environment. Profiles store the credentials and endpoint settings the CLI uses for commands.

Most users need access to both Altertable planes:

Use separate profiles when you work across organizations or environments:

Copy
altertable profile use production
altertable --profile staging profile show

3. Verify access

Check the active profile and the identity behind it:

Copy
altertable profile show
altertable profile status
altertable catalogs list

If a command fails because credentials are missing or expired, run altertable login again for the profile you want to use.

4. Query data

Run SQL against your lakehouse:

Copy
altertable query "SELECT * FROM users LIMIT 10"

Use serialized output when another process will read the result:

Copy
altertable query "SELECT * FROM events LIMIT 3" --format json
altertable --agent query "SELECT * FROM events LIMIT 3"

--agent is the recommended preset for AI agents and automation that need structured JSON without a pager, colors, or terminal styling.

5. Load data

Append one record:

Copy
altertable append --catalog warehouse --schema public --table users --data '{"id": 1}'

Upload or upsert a CSV file:

Copy
altertable upload --catalog warehouse --schema public --table users --mode overwrite --format csv --file users.csv
altertable upsert --catalog warehouse --schema public --table users --primary-key id --format csv --file users.csv

For endpoint behavior and request semantics, see the Lakehouse API reference.

6. Call the management API

The api command can call the management REST API with credentials from the active profile:

Copy
altertable api /whoami
altertable api GET /environments/production/connections
altertable api POST /environments/production/databases --body '{"name":"Analytics"}'

Use altertable api routes to list available paths and methods from the bundled OpenAPI contract.

7. Script with JSON

Use global flags before the subcommand:

Copy
altertable --json profile show
altertable --json catalogs list
altertable --agent query "SELECT 1"

With JSON output, successful responses are written to stdout. Failures write a JSON error object to stderr and leave stdout empty, which lets scripts handle errors without parsing terminal text:

Copy
1
2
3
4
5
6
7
8
if ! out=$(altertable --json profile show 2>err.json); then
  code=$(jq -r .exit_code err.json)
  message=$(jq -r .message err.json)
  echo "Altertable CLI failed ($code): $message" >&2
  exit "$code"
fi

echo "$out" | jq .

Verification

Run these commands with the active profile:

Copy
altertable profile status
altertable catalogs list
altertable query "SELECT 1 AS connected"

Confirm that the profile is authenticated, the catalog list is visible, and the query returns connected with the value 1.

Troubleshooting

• Credentials are missing or expired: run altertable login again for the intended profile.
• Commands use the wrong environment: run altertable profile use <profile> or pass --profile <profile> before the subcommand.
• Automation receives formatted terminal output: pass --json or use the --agent preset.
• A management command works but a query fails: confirm that the profile also contains valid lakehouse credentials.

Next steps

The CLI source code is available at github.com/altertable-ai/altertable-cli.

• Ingest with HTTP API: endpoint behavior behind append, upload, and upsert
• Query with HTTP API: query options and result streaming behavior
• Terraform: declarative provisioning for environments, catalogs, service accounts, credentials, and roles