# 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:

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

You can also install it from npm:

```bash
npm install -g @altertable/cli
```

Or download a prebuilt binary from [GitHub Releases](https://github.com/altertable-ai/altertable-cli/releases).

### 2. Sign in

Sign in with your browser:

```bash
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.

To create a service account profile for later automation, run this browser login once from an interactive terminal:

```bash
altertable login --service-account "CI Bot"
```

The CLI creates a separate profile with the service account's management token. See the [CLI reference](/docs/api-references/cli.md) for catalog scopes and other login options. Configure lakehouse credentials separately if the profile will query or ingest data.

Most users need access to both Altertable planes:

| Plane      | Used by                                            | Authentication        |
| ---------- | -------------------------------------------------- | --------------------- |
| Management | `profile show`, `catalogs`, and `api` commands     | Browser login         |
| Lakehouse  | `query`, `upload`, `upsert`, and `append` commands | Lakehouse credentials |

Use separate profiles when you work across organizations or environments:

```bash
altertable profile switch acme_production
altertable --profile acme_staging profile show
```

### 3. Verify access

Check the active profile and the identity behind it:

```bash
altertable profile show
altertable profile status
altertable catalogs
```

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:

```bash
altertable query "SELECT * FROM users LIMIT 10"
```

Use serialized output when another process will read the result:

```bash
altertable query "SELECT * FROM events LIMIT 3" --json
altertable --agent query "SELECT * FROM events LIMIT 3"
```

`--agent` selects structured JSON without a pager, colors, or terminal styling. The CLI also detects supported coding agents when stdout is piped and no explicit `--json` or `--format` option was supplied. Use `--agent` to force this preset or `--no-agent` to disable it. You can also set `ALTERTABLE_AGENT_MODE=1` or `0`; command-line flags take precedence.

### 5. Load data

Append one record:

```bash
altertable append '{"id": 1}' --to warehouse.public.users
```

Upload or upsert a CSV file:

```bash
altertable upload users.csv --to warehouse.public.users --mode overwrite
altertable upsert users.csv --to warehouse.public.users --key id
```

For endpoint behavior and request semantics, see the [Lakehouse API reference](/docs/api-references/lakehouse.md).

### 6. Call the management API

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

```bash
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. Develop and publish data apps

For data-app development and publishing, see the [data-app repository](https://github.com/altertable-ai/data-app).

### 8. Script with JSON

Use global flags before the subcommand:

```bash
altertable --json profile show
altertable --json catalogs
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:

```bash
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:

```bash
altertable profile status
altertable catalogs
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 switch <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](https://github.com/altertable-ai/altertable-cli).

- **[Ingest with HTTP API](/docs/ingest-data/http-api.md)**: endpoint behavior behind `append`, `upload`, and `upsert`
- **[Query with HTTP API](/docs/query-data/http-api.md)**: query options and result streaming behavior
- **[Terraform](/docs/developer-tooling/infrastructure-as-code.md)**: declarative provisioning for environments, catalogs, service accounts, credentials, and roles