Installation

Installation#

The genai command line tool is how you author, validate, and deploy an agent configuration. It is distributed as the squirro-genai Python package, which installs the genai command. This page covers what you need and how to install it.

Requirements#

Python 3.11 or later.
Your Squirro instance URL and a refresh token, so the CLI can authenticate to your cluster. A refresh token is generated in the API Access section of the Squirro settings, as described on the Authentication page. On a cluster with device login turned on, a browser signed in to the cluster replaces the refresh token, as described in the Turning On Device Login section below.

Squirro recommends installing the CLI into an isolated Python environment, such as a virtual environment, to keep it separate from other Python packages on your machine.

Availability#

The squirro-genai package is published only to the internal Squirro package index. It is not available from a public package index such as PyPI. If you are outside Squirro and want to use the genai CLI, visit the Squirro Support website and submit a technical support request for access to the package.

Install#

Install the package from an environment that is configured to reach the internal Squirro package index, such as a Squirro-managed workstation or build environment. From the default public package index, the command does not resolve.

pip install squirro-genai

To update an existing installation to a newer version:

pip install --upgrade squirro-genai

Turning On Device Login#

With device login, genai login and genai init authenticate without a refresh token. The CLI prints a short code and a link to an approval page on the cluster, and you approve the code in any browser already signed in there, on any machine. Nothing is copied back to the terminal, so this also works over SSH and inside containers. Squirro recommends turning it on for any cluster that people deploy agent configurations to.

Device login is off by default. Without it, the CLI asks for a refresh token to be pasted instead. A server administrator turns it on:

In /etc/squirro/common.ini, set the device_authorization option in the [security] section. For the file itself, see the common.ini page.
```
[security]
device_authorization = true
```
Optionally, change how long a code stays valid, in seconds, with device_authorization_expiry_secs in the same section. The default is 900, which is 15 minutes.
Restart the squserd and sqfrontendd services. The first serves the login to the CLI, and the second serves the approval page. The order does not matter.

Warning

When the audit logger is also turned on, it records request bodies verbatim, which includes the codes a device login sends. Anyone who can read the audit log while a login is waiting for approval can read its codes, and whoever holds the code the CLI polls with receives the credential once the login is approved. Restrict read access to the audit log accordingly. For the audit logger, see the Audit Logging page.

Upgrading from an Earlier Version#

Releases before targets were introduced stored the destination in each project directory. After upgrading from one of them, check the following:

A project directory that holds a .genai/target.yaml file no longer resolves. The first command you run there prints the cluster and project the file holds, and the two commands that turn them into a registered target: genai target add NAME --cluster URL --project ID, then genai target use NAME. Run both, once per project directory.
genai init takes a target. Register the destination with genai target add NAME --cluster URL --project ID, then run genai init --target NAME. The --cluster and --project flags of genai init are gone.
status, explain, log, reseed, login, logout, whoami, and the task commands take no project directory argument. Remove the path from scripts that pass one. Those commands read the target, or for login, logout, and whoami the cluster, from the directory you run them in, or from the flags and environment variables described on the CLI Reference page.
genai login without a terminal exits with an error. A login step in continuous integration fails instead of waiting for an approval. genai login does not read GENAI_API_KEY, but every other command authenticates from it directly, so remove the login step. To run the device login without a terminal on a cluster with device login turned on, for example in a container, add --use-device-code.
genai login no longer takes –manual. To paste a token by hand, run genai login --api-key-stdin, which asks for it without echoing it. On a cluster without the device login, genai login still asks for a pasted token on its own.
The GENAI_NO_INPUT variable is no longer read. Commands prompt only when standard input is a terminal, so a run without one never waits for input. Remove the variable from scripts.
Cached credentials use a new format. An earlier CLI cannot read the credentials file once the new one has written it. If you go back to an earlier version on the same machine, log in again with it.

Verify#

Confirm that the CLI is installed and available on your path:

genai --help

The command lists the available verbs, such as init, lint, deploy, and explain.

Once the CLI is installed, continue to the Quick Start page to author and deploy your first configuration.