> For the complete documentation index, see [llms.txt](https://docs.kyvvu.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kyvvu.com/cli-reference/auth.md). # 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 ```bash $ 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@company.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](#getting-an-api-key-kv_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: ``` you@company.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 ``. 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 ``."** — 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). Your `KV_API_KEY` in `~/.kyvvu/config.toml` is untouched — agents keep running. ```bash $ 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, account status, and endpoint configuration. ```bash $ kyvvu whoami Email: you@company.com API URL: https://platform.kyvvu.com Status: ✓ active Log location: https://platform.kyvvu.com (auto) Incidents: (inherits log location: https://platform.kyvvu.com (auto)) 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, which is why they are no longer one field. 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. `whoami` says so rather than guessing: ```bash $ kyvvu whoami Log location: stdout (auto — for THIS shell; an agent that supplies KV_API_KEY and KV_AGENT_KEY itself, as the kyvvu init scaffold does, resolves it to https://platform.kyvvu.com) Policy source: ✗ none — an agent here would enforce nothing (missing api_key= / KV_API_KEY, agent_key= / KV_AGENT_KEY) ``` `whoami` answers "who am I". For "why is nothing being enforced", use [`kyvvu doctor`](/cli-reference/doctor.md), 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 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 **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` * Your `KV_API_KEY`, if you keep it there instead of your shell environment — untouched by `kyvvu auth` / `kyvvu logout` *** ## Next steps * [kyvvu doctor](/cli-reference/doctor.md) — diagnose a setup that isn't enforcing anything * [kyvvu init](/cli-reference/init.md) — scaffold a new agent project * [Installation](/getting-started/installation.md) — full setup guide