---
name: cli-tokens
description: Creating, storing, and revoking CLI tokens.
---

# CLI tokens

A CLI token is a bearer credential that authenticates the `anchorify` CLI (and any other API client) as you. Tokens are scoped to a single user, can be labelled, and can be revoked individually.

## Creating a token

Sign in to the dashboard at <https://anchorify.io/dashboard>. The **CLI tokens** panel near the bottom has a form: an optional **Label** field (e.g. `laptop`, `ci-runner`) and a **Generate token** button.

On submit, the dashboard reloads with a flash banner showing the new token in cleartext, plus a pre-filled `anchorify login` command:

```bash
anchorify login --host https://anchorify.io --token jf_...
```

**Copy the token immediately.** It is shown once, and only once. We store a SHA-256 hash of it at rest; we never have the cleartext after this moment. If you lose it, revoke the token and create a new one.

## Where the token lives on disk

After running `anchorify login`, the CLI writes the host and token to `~/.config/anchorify/auth.json`, mode 600:

```json
{
  "host": "https://anchorify.io",
  "token": "jf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
```

Override the config directory with `JF_CONFIG_DIR` (useful for sandboxed testing).

## Listing your tokens

On the dashboard, the **CLI tokens** table lists every active (non-revoked) token: label, created-at, last-used. Tokens are anonymized — you cannot see the cleartext after creation, only the label.

## Revoking a token

In the **CLI tokens** table, click **Revoke** on a row. Confirm. The token is invalidated server-side immediately. Subsequent requests from any client holding that token return 401.

Revoking does not delete the token row — it marks it inactive so the audit trail (label, created-at, last-used) stays visible if you need it. If you want it gone entirely, email <sankalpagarwal294@gmail.com>.

## Rotating

To rotate:

1. Create a new token in the dashboard. Copy the cleartext.
2. Run `anchorify login --token <new-token>` on every machine that holds the old token.
3. Revoke the old token from the dashboard.

You can also revoke first and run `anchorify login` second — the CLI will fail until you provide the new token, but no requests are lost since revocation is point-in-time.

## How tokens are stored on the server

- The cleartext is hashed with SHA-256 before insert. We never store the cleartext.
- A `tokens` row has the hash, label, owner user id, created-at, and last-used-at.
- On every API request, we look up the SHA-256 of the presented bearer in the `tokens` table; if it matches a row that is not revoked, the request is authed as that row's owner.

This means an attacker who exfiltrates the database does not get usable tokens — they would need to brute-force SHA-256 against a high-entropy random secret, which is computationally infeasible.

## Environment variables (alternative)

For one-off scripts or CI runners where `auth.json` is inconvenient, the CLI accepts:

- `REPO_SHARE_HOST` — the server URL.
- `REPO_SHARE_TOKEN` — the bearer token.

When both are set, they override `auth.json`. Setting only one falls back to `auth.json` for the missing value.

The env var names are pre-rebrand. They are kept stable for scripted use.

## Legacy single-bearer token

Anchorify also supports a legacy single-bearer token via `REPO_SHARE_TOKEN` on the server. This is an admin-only token used for service operations (import/export, claim-orphans). End users do not interact with it. Per-user tokens issued from `/dashboard` are the path for everyone else.

## Next steps

- [Command-line](/docs/cli) — `anchorify login` and env-var fallbacks.
- [Web dashboard](/docs/web) — the tokens panel.
- [REST API](/docs/api) — the authentication header.