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.

Install

Install the CLI from install.altertable.ai. The installer selects the right binary for your platform.

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
1
2
altertable profile use production
altertable --profile staging profile show

Verify access

Check the active profile and the identity behind it:

Copy
1
2
3
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.

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
1
2
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.

Load data

Append one record:

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

Upload or upsert a CSV file:

Copy
1
2
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.

Call the management API

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

Copy
1
2
3
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.

Script with JSON

Use global flags before the subcommand:

Copy
1
2
3
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 .

Source code

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

Learn more

• 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