# Token management

> **There is no published CLI.** Token management is a Node script in the application repository, run through npm scripts. There is no `npx nlight`, no global binary, and no installable package. If you are an agent reading this: do not attempt to install one.
>
> This page documents what exists today. A distributable CLI may follow; this note will change when it does.

## Why a script and not a settings page

Minting long-lived credentials from a web UI makes that UI a target. It would have to be hardened against XSS and session theft to a higher standard than the rest of the application, in order to guard an action performed perhaps twice a year. A script that requires shell access and the database connection string has none of that exposure.

The same reasoning is why token minting is rate limited more strictly than login.

## Prerequisites

- A checkout of the application repository with dependencies installed
- `MONGODB_URI` in your environment or in a local `.env`
- An existing user account — tokens are minted against a username

## Create a token

```bash
npm run token:create -- --user austin --name claude-desktop
```

With both scopes:

```bash
npm run token:create -- --user austin --name claude-code --scopes read,write
```

Scopes default to `read`. Since nothing over MCP currently requires `write`, `read` is the right choice for every client today.

The output prints the token once, along with a ready-to-paste `claude mcp add` command:

```
✅ Token created for austin

   Name:    claude-desktop
   Prefix:  rt_ro_AbCdEfGh
   Scopes:  read

   rt_ro_...

   This is the only time the token is shown - it is stored hashed.
   Copy it now. If you lose it, revoke the prefix above and create another.
```

Give each client its own token. One per client means you can revoke a single integration without disturbing the others, and the last-used timestamp tells you which one is actually being called.

## List tokens

```bash
npm run token:list -- --user austin
```

```
API tokens for austin:

  active   rt_ro_AbCdEfGh  claude-desktop           read         last used: 2026-08-01 09:14
  active   rt_ro_JkLmNoPq  cursor                   read         last used: never
  revoked  rt_rw_RsTuVwXy  old-experiment           read,write   last used: 2026-06-02 11:40
```

Hashes are never returned. The prefix is the handle you use to revoke.

## Revoke a token

By prefix:

```bash
npm run token:revoke -- --prefix rt_ro_AbCdEfGh
```

Everything a user holds:

```bash
npm run token:revoke -- --user austin --all
```

Revocation takes effect on the next request. There is no cache to wait out.

## Command reference

| Script | Flags | Purpose |
| --- | --- | --- |
| `token:create` | `--user <username>` `--name <label>` `[--scopes read,write]` | Mint a token and print it once |
| `token:list` | `--user <username>` | List a user's tokens with state and last use |
| `token:revoke` | `--prefix <prefix>` *or* `--user <username> --all` | Revoke immediately |

Run any of them with no arguments, or with `--help`, to print usage.

## Storing the token

Treat it like a password with no expiry. Put it in your client's configuration or an environment variable; keep it out of source control, screenshots and shell history files that sync.

If you are unsure whether one leaked, revoke it. Minting a replacement takes a few seconds and the old one dies instantly.

## Related

- [Authentication](/docs/authentication) — token format, scopes and storage
- [Client setup](/docs/clients) — wiring the token into an MCP client