# Altertable CLI

Install the CLI, log in, and run a first query. You need an Altertable account with access to an [organization and environment](/docs/administration.md).

## Set up with your agent

```text
Set up the Altertable CLI in this environment. Follow https://altertable.ai/docs/lakehouse/clients/cli.md.

Detect my operating system, shell, and any existing CLI installation. Install or reuse the supported CLI and preserve existing profiles. Guide me through browser login, then confirm the intended organization and environment with the active profile.

Verify lakehouse credentials are available without printing them. Run SELECT 1 AS connected and confirm the returned value is 1. Use --agent when the agent consumes structured CLI output. Report the installed version, active profile, verification result, and any remaining setup. Do not ingest data or change remote resources during this setup.
```

## 1. Install the CLI

Run the installer in your terminal:

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

**Other installation methods**

Install from npm:

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

You can also download a binary for your operating system from [GitHub Releases](https://github.com/altertable-ai/altertable-cli/releases).

## 2. Log in

```altertable
altertable login
```

Complete browser login and choose your organization and environment. The CLI creates or reuses a local profile with that connection's settings.

Queries and ingestion also require [lakehouse credentials](/docs/administration/lakehouse-credentials.md). If they are missing from the profile, follow the [profile configuration reference](/docs/api-references/cli.md#altertable-profile-configure) before continuing.

## 3. Verify your first query

Check that the active profile points to the intended environment, then run a query that needs no existing table:

```altertable
altertable profile show
altertable query "SELECT 1 AS connected"
```

The query should return a `connected` column with the value `1`.

Next, [ingest your first data](/docs/getting-started/ingest-data.md) and read it back.

**More CLI workflows**

- [Query options, SQL files, and output formats](/docs/api-references/cli.md#altertable-query)
- [Append records](/docs/api-references/cli.md#altertable-append), [upload files](/docs/api-references/cli.md#altertable-upload), and [upsert rows](/docs/api-references/cli.md#altertable-upsert)
- [Manage profiles](/docs/api-references/cli.md#altertable-profile) and [log in as a service account](/docs/api-references/cli.md#altertable-login)
- [Call the management API](/docs/api-references/cli.md#altertable-api)
- [Develop data apps](/docs/api-references/cli.md#altertable-app)
- [Use the CLI with agents](/docs/agents/cli.md)

For all commands and global flags, see the [CLI reference](/docs/api-references/cli.md).

## Troubleshooting

- **Credentials expired:** run `altertable login` again.
- **Wrong environment:** [switch to the correct profile](/docs/api-references/cli.md#altertable-profile-switch).
- **Login works but queries fail:** check the profile's [lakehouse credentials](/docs/administration/lakehouse-credentials.md).