---
title: "Authentication"
canonical: https://trickest.com/docs/developer-tools/cli/authentication
description: "How the trickest CLI authenticates: API tokens, the TRICKEST_TOKEN environment variable, login, and identity checks."
---

# Authentication

Every CLI command acts as **you**, scoped to your active **vault** (your
organization/workspace). The CLI proves who you are with an **API token**.

## Token precedence

The CLI resolves your token in this order — the environment variable always wins:

1. **`TRICKEST_TOKEN` environment variable** — preferred for agents, scripts, and CI.
2. **Stored credentials** written by `trickest auth login`.

```bash
export TRICKEST_TOKEN=<your-api-token>
```

<Tip>
Get an API token from the Trickest web app under your account settings. Treat it
like a password — anyone with it can act as you.
</Tip>

## `trickest auth`

Manage authentication.

### `trickest auth status`

Report whether you're authenticated and where the token came from.

```bash
trickest auth status
```
```json
{"authenticated":true,"source":"TRICKEST_TOKEN env var","email":"you@org.com","vault":"your-vault"}
```

The `source` field tells you whether the active token is from the `TRICKEST_TOKEN env var` or stored config — useful when a stale stored token is shadowing the one you think you're using.

### `trickest auth whoami`

Resolve your identity against the backend.

```bash
trickest auth whoami
```
```json
{"email":"you@org.com","vault":"your-vault","source":"env","live":true}
```

`"live": true` means the CLI actually round-tripped the token to the server (not just read it locally), so a `true` here is a real connectivity + validity check.

### `trickest auth login`

Authenticate interactively and store the token for future commands.

```bash
trickest auth login                       # prompts for a token
trickest auth login --token <token>       # non-interactive
trickest auth login --token-file <path>   # read token from a file
```

You do **not** need to run `login` if `TRICKEST_TOKEN` is set — the env var is used directly.

### `trickest auth logout`

Clear stored credentials.

```bash
trickest auth logout
```

This only affects stored credentials; it does not unset `TRICKEST_TOKEN` in your shell.

## Confirming your user identity

`auth whoami` reports the email/vault. For the canonical user record (including the numeric user id), use:

```bash
trickest users me
```
```json
{"id":214,"email":"you@org.com","username":"you"}
```

## Vaults

Your **vault** is the scope every command operates within. It is resolved from your
token automatically and stored as `auth.vault_id` in the CLI config:

```bash
trickest config get auth.vault_id
# {"key":"auth.vault_id","value":"e54ccb18-…"}
```

You rarely set this by hand; the token determines it. See
**[Configuration & Context](/docs/developer-tools/cli/configuration)** for the full
config model.

## Troubleshooting

<AccordionGroup>
  <Accordion title="ERR_AUTH: Invalid token (exit code 2)">
    The token is missing, malformed, or rejected. Re-export `TRICKEST_TOKEN` or run
    `trickest auth login`. Confirm with `trickest auth status`.

    Note: a handful of commands (for example `billing`) may be **separately gated**
    and can return `ERR_AUTH` even when the same token works everywhere else. If
    `space ls` / `users ls` succeed but one command reports an auth error, your
    token is fine — that command is gated.
  </Accordion>
  <Accordion title="auth status says authenticated but commands fail">
    You're likely pointed at the wrong backend. Unset `TRICKEST_BASE_URL` if it
    is set in your environment, then retry against `https://trickest.io`.
  </Accordion>
  <Accordion title="Device authorization failed / Unable to connect">
    The CLI could not reach the platform. Confirm network access to
    `https://trickest.io`, then retry `trickest auth login`.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Configuration & Context" icon="gear" href="/docs/developer-tools/cli/configuration">
    The config file, active space/workflow context, and base URL.
  </Card>
  <Card title="Output & Exit Codes" icon="circle-exclamation" href="/docs/developer-tools/cli/output-and-exit-codes">
    The full error envelope and exit-code contract (incl. ERR_AUTH).
  </Card>
</CardGroup>

---
_Markdown source of https://trickest.com/docs/developer-tools/cli/authentication._