Install and sign in

Install the CLI on macOS or Linux with one line. The executable is kater.

# Get uv, Python 3.14 and the CLI, all in ~/.kater, and link kater in ~/.local/bin
curl -fsSL https://landing.kater.ai/install.sh | sh

The script uses no sudo. When ~/.local/bin is not on your PATH, it adds that folder to your shell’s profile (~/.zshrc, ~/.bash_profile or ~/.bashrc, else ~/.profile) and says so, so a new terminal finds kater. To install one version, set KATER_VERSION, such as curl -fsSL https://landing.kater.ai/install.sh | KATER_VERSION=0.2.41 sh.

The script installs the kater-cli package from PyPI. With Python 3.14 on your computer, pipx install kater-cli or uv tool install --python 3.14 kater-cli installs the same package. The CLI does not run on Windows yet.

To run the CLI from a checkout of the Kater repository, use uv:

# In the root of your checkout: install the CLI and its Python into .venv
uv sync --package kater-cli
# Put kater on your PATH in this terminal
export PATH="$PWD/.venv/bin:$PATH"

# Check which version is installed
kater --version

Then sign in once with kater login. It is the one command that opens a browser to sign in. The CLI signs in to the Kater API of your profile’s target, in ~/.kater/profiles.yml. kater init writes that profile, with Kater’s own API, when you have none. See Configuration.

# Sign in through your browser and save your credentials in the OS keychain
kater login
# Check that you are signed in, and as whom
kater auth status
# Check the profile, the project, the sign-in and each warehouse
kater debug

Every command that reads or writes content, or reaches the warehouse, needs a sign-in, such as ls, build, run, sync, here, history and admin access. Without one, it stops with “You are not signed in to the Kater API at URL.” and “Next: Run kater login.”, and exits with 2.

API login

The CLI sends every warehouse call to the Kater API of your target, which signs in to the warehouse with the organisation’s stored credential. Your computer never holds a warehouse credential. This sign-in is separate from the one that protects kater serve --mode remote.

Credentials and automation

• The keychain is required. Credentials need a supported OS keychain that is available and unlocked. There is no plaintext fallback.
• Credentials stay apart. They are kept by configuration folder, API address, auth issuer and client id.
• Automation uses a token. Give the target a token that reads the environment, such as token: "{{ env_var('KATER_CI_TOKEN') }}", and set the variable from a secret manager. The token overrides saved credentials for that Kater API, skips the keychain and refresh, and is never saved. An invalid token fails. It does not fall back to a saved login. The token is a signed-in person’s access token, and it expires. So a job that runs with nobody signed in, such as a CI pipeline, cannot use one for long yet.
• Identity comes from the sign-in. The CLI acts as the person that the token names. No environment variable sets who you are.
• HTTPS is required. API addresses need HTTPS, except loopback development hosts. Auth issuers always need HTTPS. The defaults are Kater’s own, https://api.kater.ai and https://auth.kater.ai.

1
kater:
2
  target: ci
3
  outputs:
4
    ci:
5
      type: kater
6
      api_url: https://api.kater.ai
7
      token: "{{ env_var('KATER_CI_TOKEN') }}"

# Check access in automation, with a token from your secret manager
KATER_CI_TOKEN=TOKEN kater auth status