Skip to main content
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:
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

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:
One call reports your identity, your permissions, which execution tools the organization has enabled, and which sandboxes you have running.

​
First analysis

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

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.