> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tensormesh.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Sign in to the Tensormesh Control Plane and manage local auth state.

Use Control Plane authentication for commands such as `tm auth whoami`, `tm models list`, `tm users get`, and other management workflows.

Use `tm auth status` when you need to see the local Control Plane token state
and the current inference credential state.

If `tm` is not already on your `PATH`, install the CLI first with
[Installation](/cli/guides/installation). The commands below assume `tm` is on
your `PATH`. If you are running from this repo checkout without activating a
shell that already exposes `tm`, use `./.venv/bin/tm`.

`tm auth status` reports local credential presence. Use `tm auth whoami` to confirm that the current Control Plane token still works against the live API.

## Login Flow

```sh theme={null}
tm auth login
tm auth status
tm auth whoami
```

Use that sequence in two phases:

* `tm auth status` is the local readiness check after login.
* `tm auth whoami` is the live validation step that proves the current bearer token still works against the Control Plane.

For shell scripts or CI checks, use:

```sh theme={null}
tm auth status --exit-status
```

If you are running in an environment where a browser should not be opened automatically:

```sh theme={null}
tm auth login --no-open-browser
```

The login flow fails closed after 300 seconds by default. For remote shells or automation, lower or raise that ceiling explicitly:

```sh theme={null}
tm auth login --no-open-browser --max-wait-seconds 60
```

When `TM_CONFIG_HOME` is unset, the CLI stores Control Plane tokens at
`~/.config/tensormesh/auth.json`. When `TM_CONFIG_HOME` is set, the token file
moves to `$TM_CONFIG_HOME/auth.json`.

## Automation And Headless Use

Use `tm auth whoami` when you need a live token check. It calls `GET /auth/profile`, so it validates the current bearer token against the Control Plane instead of only checking the local token file.

For controlled scripts that need the raw bearer token, use:

```sh theme={null}
tm auth print-token --yes-i-know
```

A shell-safe pattern is:

```sh theme={null}
tm --output json auth whoami
```

If you need the raw bearer token for a separate HTTP client, use `tm auth print-token --yes-i-know` only in a controlled shell.

Treat that token like a secret: avoid shell history, CI logs, and copied plaintext files.

## Refresh And Logout

Use refresh when you already have a saved login and want to update the local token set:

```sh theme={null}
tm auth refresh
```

Use logout to remove the local token file:

```sh theme={null}
tm auth logout
```

Interactive shells prompt for confirmation. Use `tm auth logout --yes` when you
want explicit non-interactive cleanup.

## CLI Login Endpoint Scope

`tm auth login` and `tm auth refresh` use the CLI browser-login flow rather than the stable raw API integration surface for external clients.

## Related Reference

* [`tm auth`](/cli/reference/auth)
* [`tm auth login`](/cli/reference/auth/login)
* [`tm auth print-token`](/cli/reference/auth/print-token)
* [`tm auth status`](/cli/reference/auth/status)
* [`tm auth whoami`](/cli/reference/auth/whoami)
* [`tm auth refresh`](/cli/reference/auth/refresh)
* [`tm auth logout`](/cli/reference/auth/logout)