Authenticate

For individual users — someone who has installed Temper and needs to authenticate against a
hosted or self-hosted instance. This is a prerequisite for every command the users door
offers.

Outcome

By the end of this page you will have an authenticated CLI session with approved access to a
Temper instance, ready to run temper warmup and work with your knowledge base.

Prerequisites

Temper installed — see Install Temper.

A deployment to authenticate against. If someone else runs the instance, ask them for
the instance URL. If you are standing it up yourself, see
Self-hosting Temper.

The sequence

1. Initialize the CLI

If you followed Install Temper, you may have already done this step.
If temper auth status works, skip to step 2.

This writes ~/.config/temper/config.toml. Answer "hosted" if you are connecting to
temperkb.io, or provide your instance URL for a self-hosted deployment.

Do not use --no-interactive with no flags. It writes provider = "none", and
temper auth login then fails with an internal error. The non-interactive hosted form
needs all four flags (--instance-url, --auth-domain, --auth-client-id,
--auth-audience), whose hosted values are published constants.

This opens a browser for an OAuth Authorization Code + PKCE flow with a localhost listener.
Your token is cached at ~/.config/temper/auth.json (0600 — a different file from
config.toml).

Check your status at any time:

It answers in two independent parts. query says whether the server could be reached at all;
entitlement — present only when it could — says what the answer was. That separation matters:
"we could not ask" and "we asked and you are denied" are opposite facts with opposite next steps.

{
  "authenticated": true,
  "expires_at": "2026-08-27T11:20:24Z",
  "identity": { "profile_id": "019d4add-…", "handle": "@your-handle" },
  "system_access": {
    "query": "reachable",
    "entitlement": { "standing": "denied", "system_access": false, "is_admin": false }
  }
}

authenticated is a local check of the cached token against its expiry; identity and
entitlement come from the server. standing is the authoritative state, and when there is
something you can do about it the command prints the command to run on stderr.

3. Request access

This step is required for every new user. A brand-new signup is born denied —
deliberately. The community edition has no paywall; an admin approving access is the
access-control mechanism. Team invitations do not confer access; requesting access moves you
from denied to requested, which is still not approved.

4. Wait for an admin to approve

Nothing before this point fails — your token is valid, your profile exists, your team
memberships are recorded. But every data call will return 403 SYSTEM_ACCESS_REQUIRED until
an admin approves you. Poll with:

Once standing reads approved, you can proceed.

If your access is revoked later

Revocation is a distinct state from never having been granted, and it has its own remedy:

auth status shows standing: "revoked" and points you at that command. Filing the request does
not restore access by itself — it asks an admin to look again.

5. Warm up

Note: warmup requires a context ref (@me/default, @handle/slug, or a UUID) and
rejects a bare name. This is different from temper pull, which takes a bare positional name
(temper pull default).

Outcome#

Prerequisites#

The sequence#

1. Initialize the CLI#

2. Sign in#

3. Request access#

4. Wait for an admin to approve#

If your access is revoked later#

5. Warm up#

Further reading#