Skip to content

kyvvu auth

What you'll learn: How to log in with the device-code flow, check your session, and log out.

kyvvu auth

Log in via a device-code flow. The CLI never collects or sees a password.

 Usage: kyvvu auth [OPTIONS]

 Log in via the device-code flow.

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮
│ --api-url             <str>  Kyvvu API URL                                                       │
│ --device-label        <str>  Label for this device (defaults to hostname)                        │
│ --help                       Show this message and exit.                                         │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯

Example

The email and device code below are illustrative. Your account and each login attempt supply their own values.

$ kyvvu auth
Opening your browser to approve this login...
If it doesn't open, visit this URL manually: https://platform.kyvvu.com/cli-auth.html?user_code=7K2M9XQP
(Code: 7K2M9XQP)

Waiting for you to approve...

✓ Logged in as you@example.com

Your browser opens automatically with the code already filled in. If you aren't already signed in to the dashboard, you'll be asked to sign in (or create an account) first — you'll land back on the same pre-filled page afterward. Confirm the code matches what's in your terminal, then click Approve (or Deny). The CLI polls in the background and returns as soon as you respond — there's no need to press anything in the terminal.

If the browser doesn't open automatically (for example, over SSH or in another headless environment), copy the printed URL — or just the code — and open it manually on any device.

On success, a personal access token (PAT) is stored locally and used to authenticate CLI commands like list-agents, list-policies, and assign-manifest. This PAT is a separate credential from KV_API_KEY — see Getting an API key below.

Waiting to be admitted

Kyvvu has a platform-wide registration limit. If it has been reached, kyvvu auth still logs you in, but you'll see this message after the login prompts:

you@example.com is waiting to be admitted.
Kyvvu is at its registration limit, so new accounts are released by
Kyvvu rather than by anyone at your organization.
Run `kyvvu whoami` to check.

Nobody at your own company can lift this — it is a property of the platform, not of your organization. That is why the message names Kyvvu rather than an administrator: being sent to a person who cannot help is worse than waiting.

A different status, ✗ suspended in this workspace, is the opposite case — one administrator in one organization has stopped you, and they can undo it.

Troubleshooting

  • "This code has expired. Run kyvvu auth again." — you didn't approve the code in time. Just run kyvvu auth again to get a fresh one.
  • "Login was denied." — the request was denied in the browser (by you or someone else with access to your account). Run kyvvu auth again if this was unexpected.
  • "Could not reach <url>. Check your network connection." — the CLI couldn't connect to the API. Check your network, or pass the right --api-url.
  • "Too many attempts. Try again in <N>." — starting a login is rate limited per IP (20 in 15 minutes). Wait the stated interval. The CLI polls at the interval the server advertises and backs off on its own if asked to slow down, so there is nothing to tune.

There's no forgotten-password flow to worry about — since there's no password, there's nothing to reset.

kyvvu logout

Revoke and clear the stored CLI session (PAT). Agents are not affected: they read KV_API_KEY from their environment or .env, not from the CLI session.

$ kyvvu logout
✓ Logged out.

kyvvu whoami

Show current user info, account status, and endpoint configuration.

$ kyvvu whoami
Email:         you@example.com
API URL:       https://platform.kyvvu.com
Status:        ✓ active
Log location:  https://platform.kyvvu.com (auto)
Incidents:     (inherits log location)
Policy source: https://platform.kyvvu.com (agent_key=my-agent)

Status is one of ✓ active, ✗ waiting to be admitted by Kyvvu, or ✗ suspended in this workspace — three states with three different remedies.

The log location shown is the resolved one, for this shell. KV_LOG_LOCATION defaults to auto, which follows the policy source, so the answer depends on KV_API_KEY and KV_AGENT_KEY — and whoami can only see what your environment sets, never what your agent passes in code.

That distinction is not academic: kyvvu init writes agent_key into agent.py and no KV_AGENT_KEY into .env.example, so in a scaffolded project this shell has no KV_AGENT_KEY while the agent supplies one. The scaffold supplies only that: it reads KV_API_KEY (and KV_API_URL) from the environment like this shell does. whoami says so rather than guessing. With KV_API_KEY exported:

$ kyvvu whoami
Email:         you@example.com
API URL:       https://platform.kyvvu.com
Status:        ✓ active
Log location:  stdout (auto — for THIS shell; the kyvvu init scaffold passes agent_key in code and resolves it to https://platform.kyvvu.com)
Incidents:     (inherits log location)
Policy source: ✗ none — an agent here would enforce nothing (missing agent_key= / KV_AGENT_KEY)

Without KV_API_KEY the Log location line names it as a condition: …passes agent_key in code and, with KV_API_KEY set, resolves it to ….

The URL it resolves to is the one the scaffold would call. KV_API_URL, when this shell (or a .env in this directory) sets it, wins. Otherwise it depends on where the CLI is logged in: kyvvu init writes a non-default session URL into .env.example as KV_API_URL, because a key from one environment is rejected by another, and whoami names that URL and says where it comes from. Logged in to another platform endpoint, with KV_API_KEY exported and no KV_API_URL. Here governance.example.com stands for that endpoint:

$ kyvvu whoami
Email:         you@example.com
API URL:       https://governance.example.com
Status:        ✓ active
Log location:  stdout (auto — for THIS shell; the kyvvu init scaffold passes agent_key in code and resolves it to https://governance.example.com, the KV_API_URL kyvvu init writes into .env.example)
Incidents:     (inherits log location)
Policy source: ✗ none — an agent here would enforce nothing (missing agent_key= / KV_AGENT_KEY)

Logged in to the default URL, or with no session, it is https://platform.kyvvu.com.

whoami answers "who am I". For "why is nothing being enforced", use kyvvu doctor, which runs the same derivations plus the policy load state, works with no session at all, and — given --agent-key — resolves the trace sink that whoami can only qualify.

Getting an API key (KV_API_KEY)

kyvvu auth logs the CLI in — it does not create an API key. KV_API_KEY is a separate, agent-scoped credential that your agent code instrumented with the Python client uses to talk to the platform, and a CLI session can never mint one on your behalf (a CLI login can't escalate itself into an agent credential). To get one:

  1. Open the dashboard.
  2. Go to Workspace → API Keys.
  3. Create a key, then set it as KV_API_KEY in your environment (or .env file).

Configuration storage

Auth state is stored in ~/.kyvvu/config.toml: - The CLI's personal access token and API URL, set by kyvvu auth and cleared by kyvvu logout

Next steps