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]

Options:
  --api-url TEXT       Kyvvu API URL
  --device-label TEXT  Label for this device (defaults to hostname)

Example

$ 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 [e-mail]

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.

Pending verification

If your organization requires admin approval for new members, kyvvu auth still logs you in, but you'll see:

Your account at company.com is pending verification.
An admin at your organization needs to approve you before you can
create agents or API keys.
Once they've approved you, run `kyvvu whoami` to check your status.

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.

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). Your KV_API_KEY in ~/.kyvvu/config.toml is untouched — agents keep running.

$ kyvvu logout
✓ Logged out. Your API key in ~/.kyvvu/config.toml is preserved
(the SDK and agents continue to work).

kyvvu whoami

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

$ kyvvu whoami
Email:         [e-mail]
API URL:       https://platform.kyvvu.com
Verification:  ✓ verified
Log location:  stdout
Incidents:     (inherits log location: stdout)

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 SDK-instrumented agent code 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 Settings → 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

• Your KV_API_KEY, if you keep it there instead of your shell environment — untouched by kyvvu auth / kyvvu logout

---

Next steps

• kyvvu init — scaffold a new agent project

• Installation — full setup guide