Skip to content
Kairo
Docs / Authentication

Getting started

Authentication

Connect a machine to your Kairo account by approving a short code in your browser. You never paste an API key.

Sign in with kairo login#

  1. Start the sign-in

    kairo login

    The CLI asks Kairo for a one-time code and prints it:

      Your code is  BCDF-GHJK

› Opened your browser to approve it.
  If nothing opened: https://joinkairo.vercel.app/cli/authorize

⠋ Waiting for you to approve it…

  2. Approve it in the browser

    Your browser opens Kairo’s Authorize the Kairo CLI page with the code already filled in. If you aren’t signed in to Kairo, you’re asked to sign in first and then brought back.

    Check that the code on the page matches the one in your terminal, then click Approve. The page also shows which machine is asking, as user@hostname.

  3. Back in the terminal

    The CLI has been waiting, and finishes on its own:

    ✓ Signed in as ada.

  email     ada@example.com
  stored    /home/ada/.config/kairo/credentials.json

How browser authorization works

kairo login uses the OAuth 2.0 Device Authorization Grant (RFC 8628) — the same flow as gh auth login or signing a TV into a streaming service.

kairo login

  1. The CLI asks Kairo for a code

  2. Your browser shows the same code

    Signed in to Kairo

  3. You check it matches and click Approve

  4. The CLI receives a token

    It has been checking every few seconds

  • Nothing secret passes through the browser. The page only sees the short code; the token goes straight to the terminal that started the sign-in.
  • It works without a browser on this machine. On a server or over SSH, nothing opens — open the printed URL on any other device, enter the code and approve it.
  • Codes expire. A code is valid for 15 minutes and can be used once. Run kairo login again for a fresh one.

Already signed in

If this machine is already signed in, kairo login tells you as whom and stops. To sign in as someone else:

kairo login --force

Check the account with kairo whoami#

kairo whoami

  username  ada
  email     ada@example.com
  name      Ada Lovelace

  https://joinkairo.vercel.app

whoami asks Kairo rather than reading a saved copy, so it doubles as a health check: if it prints your account, your sign-in works and Kairo is reachable. The last line is the server the CLI is talking to.

Sign out with kairo logout#

kairo logout

✓ Signed out. That token has been revoked.

Logging out deletes the stored token from this machine and revokes it on Kairo, so a copy taken from the disk stops working too.

  • If Kairo can’t be reached, the token is still deleted locally, and the CLI warns that it wasn’t revoked server-side.
  • Signing out on one machine doesn’t affect your other machines, or your browser session on the website.

How long a sign-in lasts#

Each approval signs in one machine. The token lasts 90 days, or until you run kairo logout on that machine. When it stops working, the next command says That sign-in is no longer valid, removes the stored copy, and asks you to run kairo login again.

Using a token instead (CI)#

Where no one can approve a code, set KAIRO_TOKEN and the CLI uses it instead of a stored sign-in. While it is set, kairo login and kairo logout refuse to run and tell you to unset it.