Altertable CLI reference

Usage

altertable login [options]

Options

--control-plane-url <CONTROL-PLANE-URL>string

Control-plane server root to log in against; saved to the profile only on success (the CLI appends /oauth and /rest/v1). Default: https://app.altertable.ai

--data-plane-url <DATA-PLANE-URL>string

Data-plane base URL saved to the profile only on successful login. Default: https://api.altertable.ai

--allow-insecure-httpboolean

Allow http:// URLs other than localhost for --control-plane-url (for development only)

--replace-profileboolean

Store the login session in the current profile instead of switching profiles

--org <SLUG>string

Preselect this organization in the browser authorization page

--env <SLUG>string

Preselect this environment in the browser authorization page

--service-account <LABEL>string

Create an environment-scoped service account with this label and store its access token instead of your login session

--scope <MODE|CATALOG:MODE,...>string

Request a service account limited to `ro` or `rw` on every catalog, or to specific catalogs, e.g. `analytics:ro,staging:rw` (requires --service-account). The catalog access the server actually grants is reported on success.

Usage

altertable logout [options]

Options

--except-currentboolean

Keep the current profile and remove every other profile

Usage

altertable profile configure|list|show|status|switch|current|env|delete

Usage

altertable profile configure [options] [NAME]

Arguments

<NAME>positional

Profile name (default: selected or active profile)

Options

--user <USER>string

Lakehouse username (global)

--password <PASSWORD>string

Lakehouse password (global)

--basic-token <BASIC-TOKEN>string

Pre-encoded HTTP Basic token

--api-key <API-KEY>string

Management API key for the --env environment

--env <ENV>string

Target environment (management API keys are per-environment)

--password-stdinboolean

Read the lakehouse password from stdin

--api-key-stdinboolean

Read the management API key from stdin

--data-plane-url <DATA-PLANE-URL>string

Data-plane base URL; can be set alone or with a credential (default: https://api.altertable.ai)

--control-plane-url <CONTROL-PLANE-URL>string

Control-plane server root; the CLI appends /rest/v1 (default: https://app.altertable.ai)

--allow-insecure-httpboolean

Allow http:// URLs other than localhost (not recommended)

--scope <SCOPE>enum

Limit the interactive wizard to one plane (default: both)

Supported values

managementlakehouse

Usage

altertable profile list

Usage

altertable profile show [NAME]

Arguments

<NAME>positional

Profile name (default: selected or active profile)

Usage

altertable profile status [NAME]

Arguments

<NAME>positional

Profile name (default: selected or active profile)

Usage

altertable profile switch [NAME]

Arguments

<NAME>positional

Profile name

Usage

altertable profile current

Usage

altertable profile env [NAME]

Arguments

<NAME>positional

Profile name (default: active profile)

Usage

altertable profile delete [options] <NAME>

Arguments

<NAME>positional· Required

Profile name

Options

--yesboolean

Confirm deletion

Usage

altertable catalog

altertable catalog create

Usage

altertable catalog create <NAME>

Arguments

<NAME>positional· Required

Catalog name

Usage

altertable api [options] <ENDPOINT>

altertable api route|spec

Arguments

<ENDPOINT>positional· Required

Path under /rest/v1, e.g. /whoami

Options

-X, --method <METHOD>enum

HTTP method override (default GET, or POST when fields/input are provided)

Supported values

GETPOSTPATCHDELETEPUT

-f, --raw-field <RAW-FIELD>string· Repeatable

String request parameter key=value (repeatable; gh api -f semantics)

-F, --field <FIELD>string· Repeatable

Typed request parameter key=value (true, false, null, integers; repeatable)

--input <INPUT>string

File to use as the request body; use - for stdin

--env <ENV>string

Replace {environment_id} in the path

--format <FORMAT>enum

Serialized output format; use global --json for JSON

Supported values

csvmarkdown

Usage

altertable api route [OPERATION]

Arguments

<OPERATION>positional

Optional operationId to inspect, e.g. createDatabase

Usage

altertable api spec

Usage

altertable doctor [options]

Options

--offlineboolean

Inspect local configuration without contacting Altertable APIs.

Usage

altertable app create|dev|build|lint|upgrade|validate|publish|update

Usage

altertable app create [options] <NAME>

Arguments

<NAME>positional· Required

App name in kebab-case

Options

--dir <DIR>string

Destination directory (default: ./<name>).

--without-profileboolean

Create an offline scaffold with organization and environment placeholders.

Usage

altertable app dev [options]

Options

--dir <DIR>string

App directory (default: current directory).

--port <PORT>string

Local dev server port (1–65535; default: app setting).

Usage

altertable app build [options]

Options

--dir <DIR>string

App directory (default: current directory).

Usage

altertable app lint [options]

Options

--dir <DIR>string

App directory (default: current directory).

--lakehouseboolean

Run each operation’s declared checks against the selected lakehouse.

Usage

altertable app upgrade [options]

Options

--dir <DIR>string

App directory (default: current directory).

Usage

altertable app validate [options]

Options

--file <FILE>string· Required

Path to the single-file React source (index.tsx). Queries are declared in the file via defineDataApp.

Usage

altertable app publish [options]

Options

--title <TITLE>string· Required

Title of the data app.

--file <FILE>string· Required

Path to the single-file React source (index.tsx). Queries are declared in the file via defineDataApp.

--description <DESCRIPTION>string

Optional description of the data app.

Usage

altertable app update [options] <SLUG>

Arguments

<SLUG>positional· Required

Data app slug to update (e.g. APP-1).

Options

--title <TITLE>string

New title of the data app.

--file <FILE>string

Path to replacement single-file React source (index.tsx). Replaces the queries with those the file declares.

--description <DESCRIPTION>string

New description of the data app.

Usage

altertable update [options] [VERSION]

Aliases

upgrade

Arguments

<VERSION>positional

Specific version to install (default: latest).

Options

--checkboolean

Check for an update without installing it.

--forceboolean

Reinstall or downgrade to the selected release.

Usage

altertable completion

altertable completion generate|install

Usage

altertable completion generate <BASH|FISH|ZSH>

Arguments

<SHELL>positional· Required

Shell to generate completion for

Supported values

bashfishzsh

Usage

altertable completion install [options] [BASH|FISH|ZSH]

Arguments

<SHELL>positional

Shell to install completion for (default: detected shell)

Supported values

bashfishzsh

Options

--no-rcboolean

Write the completion file without updating shell startup files.

Usage

altertable append [options] <DATA>

altertable append status

Arguments

<DATA>positional· Required

JSON object, array, or @file

Options

--to <TO>string· Required

Destination as catalog.schema.table

--syncboolean

Wait for the append operation to finish before returning

Usage

altertable append status <APPEND-ID>

Arguments

<APPEND-ID>positional· Required

Append id returned by append

Usage

altertable upload [options] <FILE>

Arguments

<FILE>positional· Required

Local file to upload

Options

--to <TO>string· Required

Destination as catalog.schema.table

--format <FORMAT>enum

Input format; inferred from the filename when omitted

Supported values

csvjsonparquet

--mode <MODE>enum

create, append, or overwrite

Supported values

createappendoverwrite

Default

create

Usage

altertable upsert [options] <FILE>

Arguments

<FILE>positional· Required

Local file to upload

Options

--to <TO>string· Required

Destination as catalog.schema.table

--format <FORMAT>enum

Input format; inferred from the filename when omitted

Supported values

csvjsonparquet

--key <KEY>string· Required

Column name used to match existing rows

Usage

altertable query [options] <STATEMENT>

altertable query show|cancel

Arguments

<STATEMENT>positional· Required

SQL statement to run

Options

--format <FORMAT>enum

Result format: csv, jsonl, and parquet stream from the API; markdown is rendered by the CLI. Use global --json for structured JSON

Supported values

csvjsonlparquetmarkdown

--layout <LAYOUT>enum

Human layout: auto, table, or line

Supported values

autotableline

--columns <COLUMNS>string

Comma-separated columns to show

--max-width <MAX-WIDTH>string

Maximum display width for table columns

Default

32

--compute-size <COMPUTE-SIZE>string

Compute size for the query

Default

AUTO

--dialect <DIALECT>string

Source SQL dialect to transpile from (server default: DuckDB)

--catalog <CATALOG>string

Catalog name (optional; can also come from the session)

--schema <SCHEMA>string

Schema name (optional; can also come from the session)

--output <OUTPUT>string

Write result bytes/text to this path instead of stdout

--query-id <QUERY-ID>string

Optional stable query id

--session-id <SESSION-ID>string

Optional session id

--pager <PAGER>enum

Pager mode for human output: auto, always, or never

Supported values

autoalwaysnever

Default

auto

Usage

altertable query show <QUERY-ID>

Arguments

<QUERY-ID>positional· Required

Query id returned by the API

Usage

altertable query cancel [options] <QUERY-ID>

Arguments

<QUERY-ID>positional· Required

Query id to cancel

Options

--session-id <SESSION-ID>string· Required

Session id that owns the query

Usage

altertable schema [options] <CATALOG>

Arguments

<CATALOG>positional· Required

Catalog name

Options

--format <FORMAT>enum

Serialized output format; use global --json for JSON

Supported values

csvmarkdown

--pager <PAGER>enum

Pager mode for human output: auto, always, or never

Supported values

autoalwaysnever

Default

auto

Usage

altertable duckdb [CATALOG]

Arguments

<CATALOG>positional

Catalog to attach (defaults to all catalogs)