> For the complete documentation index, see [llms.txt](https://docs.visdom.virtuslab.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.visdom.virtuslab.com/visdom-tracing/user-guide/installing-tracevault-and-signing-in.md).

# Installing the CLI and signing in

The CLI installs one binary, `tracevault`. Install it from the VirtusLab Homebrew tap or from [crates.io](https://crates.io).

```bash
brew install VirtusLab/visdom-ai-tracing/tracevault

# or
cargo install tracevault-cli
```

## Humans sign in with `tracevault login`

`tracevault login` uses the OAuth 2.0 **device authorization grant** (RFC 8628) against your organisation's Keycloak, the same flow as `gh auth login` or signing in on a smart TV. The CLI first asks the server which realm it trusts (`GET /api/v1/auth/public-config`), then talks to Keycloak directly. Your password never reaches the tracing server.

```bash
tracevault login --server-url https://your-tracevault-server.example.com
```

The command prints a verification URL and a one-time code. It then tries to open a browser and waits for you to approve. Pass `--no-browser` to only print the URL; headless, CI and container sessions imply that flag.

On success the CLI writes `~/.config/tracevault/credentials.json` with mode `0600`. The file holds a short-lived access token and a long-lived `offline_access` refresh token, and the command prints the account and role the server resolved.

That refresh token is what makes unattended use work. Every command refreshes the access token by itself shortly before it expires, so git hooks and background captures never stop to prompt. Nothing has to be re-run periodically.

{% hint style="success" %}
**Sign-in succeeded but the server says "not authorized".** The Keycloak account is missing the `tracing` realm role. The credentials are already saved, so nothing needs re-running: an administrator grants `tracing` (or `tracing-admin`), and every `tracevault` command works from that moment on.
{% endhint %}

`tracevault logout` revokes the refresh token at Keycloak and deletes the credentials file. Revocation is best-effort; the local file is removed either way.

## CI and automation use an API key

CI does **not** use `tracevault login`. It uses a long-lived API key, which never expires and needs no browser.

```bash
export TRACEVAULT_SERVER_URL=https://your-tracevault-server.example.com
export TRACEVAULT_API_KEY=tvk_...
```

`TRACEVAULT_API_KEY` takes precedence over the credentials file. A key set in the environment always wins, even on a machine that also has an interactive login. Worth knowing when a local run behaves like CI for no visible reason.

A server deployed without Keycloak supports only the API-key path. In that case `tracevault login` says so, instead of starting a flow that cannot finish.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.visdom.virtuslab.com/visdom-tracing/user-guide/installing-tracevault-and-signing-in.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.