Skip to main content
failproofai auth login    # email + one-time code
failproofai auth logout   # revoke this session
failproofai auth whoami   # print the signed-in identity
The legacy --login / --logout / --whoami flag form is still accepted as an alias for back-compat. Authentication is opt-in. Policies, the dashboard, the /audit page, and every other local feature work exactly the same whether you’re signed in or not. The login surface exists so that features that need a stable identity (re-audit reminders today, more in the future) have somewhere to anchor.

​
Sign-in flow

failproofai auth login
Prompts for your email, sends a 6-digit one-time code to that address, prompts for the code, and on success writes ~/.failproofai/auth.json (mode 0600). The same session is then visible to the in-app dashboard — clicking [ set a reminder ] on /audit will see you as signed in. The dashboard exposes the same flow as a modal dialog on /audit for users who never touch the CLI.

​
Sign-out

failproofai auth logout
Revokes the current session on the server and deletes ~/.failproofai/auth.json. If the api-server is unreachable, the local file is removed regardless — local intent to log out always wins.

​
Identity check

failproofai auth whoami
Prints <email> (<user uuid>) and exits 0 when a valid session exists, or not signed in and exits 1 otherwise. Silently refreshes the access token in the background if it’s within a minute of expiring.

​
Persistent re-audit reminder

When you click [ set a reminder ] on the /audit page (or sign in via the modal that the button gates on), the dashboard writes a small companion file at ~/.failproofai/next-audit.json: 
{
  "next_audit_at": 1780765200,
  "user_email": "you@example.com",
  "set_at": 1780160574
}
This file is scoped to the email it was set for — switching the CLI session to a different account hides any reminder that belongs to the previous user. Default offset is 7 days, configurable later when the scheduler lands. Created with 0600 perms like auth.json. The dashboard’s /api/auth/reminder endpoint exposes GET (read), POST (set / reschedule), and DELETE (clear) and requires an active session.

​
What’s in ~/.failproofai/auth.json

{
  "access_token": "eyJhbGc…",
  "refresh_token": "9ede3e…",
  "access_expires_at": 1780160574,
  "refresh_expires_at": 1782748974,
  "user": { "id": "<uuid>", "email": "you@example.com" }
}
Created with 0600 perms (owner-only read/write). The access token is a 1-hour HS256 JWT; the refresh token is an opaque 256-bit random string that the server stores as SHA-256(token). Refresh-token replay is detected server-side and revokes every session for the user.

​
Environment variables

VariableDefaultPurpose
FAILPROOF_API_URLhttps://api.befailproof.aiOverride the api-server base URL. Useful for local development against a self-hosted api-server.
FAILPROOFAI_AUTH_DIR~/.failproofaiOverride where auth.json is stored. Mostly for tests.
See Environment variables for the full list.

​
Troubleshooting

“Could not reach the api-server” — the CLI can’t open a TCP connection to FAILPROOF_API_URL. Check your network, or set FAILPROOF_API_URL if you’re running a self-hosted api-server. “Rate limited” — too many login attempts in a 15-minute window for that email (5/email) or IP (20/IP), or a 30-second resend cooldown after the previous request for the same email. The error message includes the retry-after window in seconds. Code rejected — the OTP was wrong, expired, or the row hit its 5-wrong-guess lockout. Run failproofai auth login again to request a fresh code.