memtrace auth

Sign in or out of your Memtrace license with a browser-based device flow. Powers the first-run gate in memtrace start and memtrace mcp.

Usage#

memtrace auth [login|logout]

memtrace auth manages the local session credentials stored at ~/.config/memtrace/credentials.json (XDG-aware — resolved via XDG_CONFIG_HOME, then HOME/.config, then USERPROFILE/.config). memtrace auth login runs, or resumes, a browser-based device flow against memtrace.io and saves a session. memtrace auth logout deletes the credentials file.

You won't usually type this command yourself: memtrace start and memtrace mcp both run the same login flow inline on first run, before anything else happens.

AUTH IS UNDOCUMENTED ON PURPOSE

auth and its subcommands don't appear in memtrace help's command list. It's reachable, and other commands print a "Then run: memtrace auth login" hint on auth failure — but it isn't part of the advertised surface.

memtrace auth login first checks whether a usable session already exists — dev mode, a MEMTRACE_LICENSE_KEY, an offline license, or a valid session token already in credentials.json. If one does, login takes the fast path: it prints ✓ Already signed in (<edition>)., prints the credentials file path, and exits. No network call, no device flow, nothing written.

If there's no usable session, login prints why (unless it's simply a fresh install with no credentials at all, which is treated as expected and silent) and starts the full device flow described below.

EVERY UNRECOGNIZED VERB RUNS LOGIN

Dispatch reads the word after auth and matches only the literal string logout; every other value — login itself, no verb at all, a typo, or even memtrace auth status — falls through to the login path. There is no auth status subcommand; typing one will silently kick off a real device flow instead of erroring. Session and degradation status live in memtrace status instead, which reads the same auth-session state.

SWITCHING ACCOUNTS

Login is idempotent when you're already signed in — it won't silently replace your session. To switch accounts, run memtrace auth logout first, then memtrace auth login.

logout#

memtrace auth logout deletes the entire credentials.json file — license key, session token, edition, org/seat identity, and any MemDB tokens written by memtrace connect — then prints a message telling you to re-run memtrace auth login. It always exits 0, even if the file was already gone.

LOGOUT IS BROADER THAN CONNECT --DISCONNECT

Because logout removes the whole file, it also wipes any MemDB bearer tokens installed by memtrace connect — not just your license/session. If you only want to disconnect from an external MemDB endpoint and keep your license signed in, use memtrace connect --disconnect instead, which is scoped to just team.toml plus the stored token.

The device flow#

The interactive flow has four steps, all outbound HTTPS to memtrace.io — it opens no local port:

Mint a device code: POST {base_url}/api/device/code.
Build the claim URL ({base_url}/claim?code={device_code}), print it, and best-effort open it in the OS browser (unless suppressed).
Enter a waiting room that polls GET {base_url}/api/device/poll?code=... every 15 seconds until the code is claimed.
Exchange the returned license key for a session via POST {base_url}/api/device/auth, sending a stable per-machine device ID so reinstalling on the same machine reuses the same server-side install slot.

On a TTY with a display, the waiting room is a full-screen terminal UI. Its sign-in URL sits in its own always-visible block — it doesn't get lost behind a browser window that failed to open or opened underneath the terminal. Three keys work inside it:

o or Enter — reopen the claim URL in the browser.
r — reopen the referral URL, if one exists for your invite.
q or Ctrl-C — cancel. Your queue position/claim is preserved server-side, so a later memtrace auth login resumes rather than restarting.

On the successful exchange, login writes credentials.json with a read-modify-write merge: it preserves any existing MemDB tokens from memtrace connect and other unknown fields, only merging in the license key, session token, expiry, edition, and (if present) org/seat identity.

Device-code login flowSEQUENCE

memtrace auth login

Browser

memtrace.io

SERVICEEXTERNALSUPPORTING

Non-interactive alternatives#

To skip the browser flow entirely, provide a license key before login ever reaches the browser device flow:

terminal

$ MEMTRACE_LICENSE_KEY=<key> memtrace auth login

A valid license key makes login report that you are already signed in.

On headless shells (CI=1, no display, or MEMTRACE_HEADLESS), the browser auto-open and the full-screen waiting-room TUI are both skipped automatically. The claim URL is still printed for manual copy-paste, and a plain polling loop (an eprintln line every 15 seconds with queue position) takes the TUI's place.

Degraded mode#

An account is required — a truly anonymous memtrace mcp invocation with no credentials anywhere is refused. But once you're licensed, a network blip won't stop you from working: a transient auth failure (memtrace.io unreachable, timeout) boots the server in degraded mode, which keeps serving tools normally and re-validates the license in the background every 5 minutes. Only a definitive cloud rejection — a 401/403 for a revoked, invalid, or suspended license — actually exits.

MULTI-DEVICE IS EXPECTED, NOT ABUSE

Using the same license key to sign in on more than one machine is explicitly allowed — billing is metered by query credits, not by seat. Multi-device use is not a rejection condition in the startup auth decision.

Environment variables#

Variable	Default	Description
`MEMTRACE_AUTH_URL`	`https://www.memtrace.io`	Base URL for the device-code mint, claim URL, poll endpoint, and license exchange. Overrides for pointing login at a local/staging server.
`MEMTRACE_LICENSE_KEY`	—	Headless/CI license key. If valid, login reports already-signed-in and skips the device flow.
`MEMTRACE_OFFLINE`	—	Forces the offline-license path (`~/.config/memtrace/license.mtl`) instead of the online exchange. If that stored license is valid, login sees an existing offline session and reports already-signed-in.
`MEMTRACE_HEADLESS / CI`	—	Suppresses the browser auto-open during the device flow; the claim URL is still printed, and the plain polling loop replaces the full-screen waiting-room TUI.
`XDG_CONFIG_HOME / HOME / USERPROFILE`	`OS-dependent`	Resolution chain for the credentials directory, in order, with a temp-dir fallback last — so a reduced-env MCP host doesn't lose a completed login. Final path: `<dir>/memtrace/credentials.json`.

Gotchas#

NO LOCAL PORT, NO LOCALHOST URL

The device flow is purely an outbound HTTPS client to memtrace.io plus a local terminal UI — unlike memtrace start/memtrace mcp, which bind 127.0.0.1:3030. Don't look for a loopback callback here.

NEEDS A REAL TTY, OR IT AUTO-FALLS-BACK

The waiting room is a full-screen crossterm alt-screen UI. It misbehaves if stdout/stderr isn't a real TTY — which is exactly why headless, CI, and no-DISPLAY Linux shells are auto-detected and routed to the plain polling fallback instead of trying to render it anyway.

CANCEL PRESERVES YOUR CLAIM

Pressing q or Ctrl-C in the waiting room returns an error from memtrace auth login's point of view, but your queue position/claim is kept server-side — a later memtrace auth login retry resumes rather than starting over.

Examples#