Set Your API Key

Mentu uses API keys prefixed with mk_ for authentication with the Epistemic Oracle at api.mentu.ai.

Register

mentu auth login you@example.com

This sends a registration request to api.mentu.ai/auth/register. On success:

  ✓ Authenticated as you@example.com
  Tier: free
  Key stored at ~/.mentu/credentials.json

The API key is stored locally at ~/.mentu/credentials.json with owner-only permissions (chmod 600).

When mentu needs an API key, it checks three sources in order:

Priority	Source	Description
1	`MENTU_API_KEY` env var	Environment variable — highest priority
2	`mentu.yml` `api_key` field	Workspace configuration file
3	`~/.mentu/credentials.json`	Stored credentials from `mentu auth login`

The first non-empty value wins. This lets you override per-session or per-workspace without modifying stored credentials.

mentu auth status

Displays your email, tier, key prefix, and live usage from the Oracle:

  Email: you@example.com
  Tier:  free
  Key:   mk_live_abcde…
  Usage: 42/1000 (958 remaining)
  Resets: 2026-04-04T18:00:00Z (resets in 3h 15m)

mentu auth logout

Deletes ~/.mentu/credentials.json. After logout, mentu falls back to MENTU_API_KEY env var or mentu.yml.

The free tier includes rate limiting with a 4-hour sliding window. Use mentu auth status to check your current usage and when the window resets.

HTTP Status	Meaning
`400`	Invalid email address
`409`	Email already registered — run `mentu auth logout` first
`429`	Rate limited — too many registration attempts
`500+`	Server error — check status.mentu.ai

If the Oracle is unreachable, mentu auth status shows "Quota: unavailable (Oracle offline)" but local operations continue to work.