Configuration

A command finds where it runs from two files, as dbt does. The project file, kater_project.yml, marks your local copy and names a profile. The profile, in profiles.yml, lists its targets, and each target names a Kater API. Run kater debug to see which profile and target a command uses, and to check each part of the setup.

The project file

kater git clone writes kater_project.yml at the root of your local copy. In a copy made before, kater git pull writes it. Git never lists it, and kater git push never sends it.

1
name: kater
2
version: "1.0"
3
config-version: 1
4
profile: kater

A command looks for this file in the folder you run it from and in each folder above. A command that reads content stops with exit status 2 when it finds none. --kater-root or KATER_ROOT names the project folder in its place.

The profile

profiles.yml holds one entry for each profile. A profile names its default target and lists its targets under outputs.

1
kater:
2
  target: dev
3
  outputs:
4
    dev:
5
      type: kater
6
      api_url: http://127.0.0.1:8788
7
    prod:
8
      type: kater
9
      api_url: https://api.kater.ai

• Every target is a Kater API. type is always kater. Warehouse calls go through that Kater API, with the credential it stores for each connection. Your computer never holds a warehouse credential.
• Sign-in settings. A target can also set auth_url, client_id, redirect_uri and site_url. Without them, kater login asks the Kater API for its own.
• A token for automation. A target can set token. It replaces the sign-in that kater login saves, for that Kater API only. Write it as {{ env_var('KATER_CI_TOKEN') }}, never as the token itself.
• Values from the environment. Any value can be {{ env_var('NAME') }}, or {{ env_var('NAME', 'default') }} with a default. A variable that is not set and has no default stops the command with exit status 2.
• Errors name the key, never the value. An invalid value stops the command with exit status 2 and names the file and the key, such as kater.outputs.dev.api_url.
• The project must agree. When the local copy’s .git/kater.json names a Kater API, the target must name the same one.

kater init writes the profile kater, with the target prod at Kater’s own API, when you have no profile.

Which profile and target

--target, --profile and --profiles-dir can come before or after the command, such as kater run --select query.sql --target prod.

Other settings

These settings come from a flag, else the environment, else the default.

• Another configuration folder. KATER_CONFIG_DIR selects another absolute configuration folder and credential namespace, and its profiles.yml. It does not move the saved scope at ~/.kater/scope.json.
• Jobs stay explicit. Job commands do not take development defaults. They still need --deployment, and they load a dotenv file only through --env-file.
• Help and version are fast. They do not read the profile or resolve credentials.