> ## Documentation Index
> Fetch the complete documentation index at: https://docs.textql.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Install the ana command-line tool, sign in, and point a coding agent at it

`ana` is TextQL's command-line tool. It queries a connector into a remote Python
session and runs Python or shell in that session, so an analysis can be driven
from a terminal — or by a coding agent — instead of the browser.

## Install

**TextQL cloud:**

```bash theme={null}
curl -fsSL https://cli.textql.com/cli/install.sh | sh
```

**Every other deployment** — VPC, on-prem, staging — serves its own copy of the
CLI, and the download requires you to be signed in. Get it from the browser:
**Settings → Desktop & CLI** detects your operating system, offers the matching
build, and shows the command to unpack it. On a white-labeled deployment the
same page is named **Settings → CLI**.

A piped `curl | sh` cannot carry your session, so running one against your own
deployment returns 401. That is expected, and not something an administrator can
switch off.

The installer detects your platform, verifies the download against a checksum,
and installs to `/usr/local/bin`, falling back to `~/.local/bin` when that is
not writable. Set `TEXTQL_INSTALL_DIR` to choose somewhere else. It also
installs a man page where it can, so `man ana` works.

Builds are provided for macOS (Apple Silicon and Intel) and Linux (x86\_64 and
arm64). There is no Windows build.

## Sign in

```bash theme={null}
ana auth login
```

This opens a browser approval for your account — there is no API key to copy
around. `ana auth status` shows who you are and what the grant allows, and
`ana auth upgrade` widens it if a command reports a missing scope.

Then confirm what the deployment allows:

```bash theme={null}
ana info
```

One call reports your identity, your permissions, which execution tools the
organization has enabled, and which sandboxes you have running.

## First analysis

```bash theme={null}
ana connector db list
ana connector db query 7 --sql 'select * from orders limit 1000' --as orders
ana exec python 'print(orders.describe())'
```

The query result lands as a dataframe named `orders` inside a remote Python
session, and the next `ana exec python` call sees it. Sandboxes are named
(`--sandbox revenue-q3`), each has its own kernel, and the state in one carries
across calls until it is idle long enough to be reclaimed.

`man ana` documents every command, the exit codes, and the environment
variables.

## Versions

**The CLI version available to you is the one your deployment ships**, and it
upgrades itself from that deployment — never from anywhere else. A new release
reaches your users when your TextQL server is upgraded, not before.

That is deliberate: the CLI a user runs always speaks the same API as the server
it is talking to, so a long-lived deployment never has to cope with a newer
client. It holds for cloud users who installed with the one-liner too — the
install URL is not consulted again afterwards.

`ana update --check` reports what your deployment ships without changing
anything; `ana update` applies it.

## Teaching an agent to use it

```bash theme={null}
ana install skill --claude
```

writes a skill file that teaches a coding agent how to drive the CLI — how to
sign in, how to load data into a sandbox and analyze it there, which operations
need which permissions, and how to keep out of the way of other sessions. Add
`--project` to install it into the current repository instead of your home
directory.

## Who can download

The download routes require authentication — a browser session or a bearer
token — on **every** deployment, including TextQL's cloud. Your deployment never
serves its artifacts to an unauthenticated caller, so a deployment behind a VPN
or in an air-gapped VPC stays that way.

The public one-liner is not an exception: it points at a separate static host
carrying only the builds TextQL's cloud is running, not at any deployment.

Downloads are rate limited per client address and support resumable range
requests, so an interrupted download continues rather than starting over.

## Troubleshooting

**The Settings page has no CLI section.** It hides itself inside the desktop
app, where a shell is already at hand. It is *not* hidden for white-labeled
deployments — look for **CLI** rather than **Desktop & CLI**.

**`curl | sh` returns 401.** Expected against your own deployment: downloads are
authenticated everywhere. Cloud users install from
`https://cli.textql.com/cli/install.sh`; everyone else uses **Settings →
Desktop & CLI**.

**The download 404s.** The deployment predates CLI support — upgrade it.

**A command exits 3.** The grant is missing a scope. Run `ana auth upgrade`.

**A command exits 4.** Your organization has that execution tool disabled. Run
`ana info` to see which are available, and ask an administrator to enable it.