Skip to main content
DocumentationLibraryReference
On this page

Kater CLI Set up

kater login

Signs you in to the Kater API of your target through your browser, and saves your credentials in your computer's keychain.

You sign in one time, and the CLI refreshes your sign-in when it expires. Commands that reach Kater need it, such as kater git clone. Commands that only read your files do not.

Examples

Terminal window
# Sign in to the Kater API of your profile's default target
kater login
# Sign in to the Kater API of the prod target
kater login --target prod
# Check that you are signed in, and as whom
kater auth status

Options

It also takes the global options --json and --help.

How the sign-in works

  1. The CLI opens your default browser on the sign-in page. It waits up to 3 minutes for you to sign in.
  2. The browser comes back to the CLI on your own computer. When another program uses that port, close that program and try again.
  3. The CLI asks the Kater API who you are. When the API does not accept the sign-in, the CLI saves nothing.

Which Kater API

The target’s api_url in profiles.yml names the Kater API. When there is no profiles.yml, kater login writes ~/.kater/profiles.yml with the profile kater, whose target prod is Kater’s own API, as kater init does. --target and --profile select another target or profile. See Configuration. kater debug shows the target that a command uses.

Where your sign-in is kept

  • In your keychain. The CLI keeps your credentials in macOS Keychain, Windows Credential Locker, or Secret Service or KWallet on Linux. The keychain must be available and unlocked. The CLI never writes them to a plain file.
  • Without a keychain. On a computer with no keychain, such as a server, give the target a token from the environment, such as token: "{{ env_var('KATER_CI_TOKEN') }}". See Install and sign in.
  • One sign-in for each Kater API. The CLI keeps one token for each Kater API. Every target that names the same Kater API uses that one sign-in.
  • Your addresses. The sign-in address, the client id and the address your browser comes back to come from the target’s auth_url, client_id and redirect_uri. Without them, the CLI gets them from the Kater API, at GET /v1/sign-in-config, the first time you sign in to it. It accepts only an HTTPS sign-in address, or a localhost address for a Kater API on localhost. It saves them for that API in ~/.kater/sign-ins.json. These values are not secrets.

See also