Authentication

Coldrune uses passwordless authentication. No passwords to remember or rotate.

Magic link login

# Request a 6-digit code via email
coldrune auth login --email you@example.com

# Verify the code
coldrune auth verify --code 123456

The code expires after 10 minutes. An incorrect guess invalidates the code immediately — you’ll need to request a new one.

Your session token is stored at ~/.config/coldrune/session with 0600 permissions.

Check your identity

coldrune auth whoami

Log out

coldrune auth logout

Dev mode

Set SMTP_HOST=log in your .env to print login codes to the server terminal instead of sending email. No SMTP credentials required.

API key authentication

For CI/CD and automation, use service accounts instead of interactive login. Service accounts authenticate with an API key via the X-API-Key header.

The CLI auto-detects the auth method:

Source	Prefix	Header
Session file	(none)	Authorization: Bearer <token>
COLDRUNE_API_KEY env var	cr_sa_	X-API-Key: <key>

Rate limits

Action	Limit
Login requests	5 per email per 15 minutes
Failed verifications	10 per email per hour (hard lockout)

Caution

After 10 failed verification attempts in an hour, the email is locked out. Wait for the lockout window to pass.

REST API

# Request code
curl -X POST http://localhost:7100/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email": "you@example.com"}'

# Verify code
curl -X POST http://localhost:7100/api/auth/verify \
  -H 'Content-Type: application/json' \
  -d '{"email": "you@example.com", "code": "123456"}'
# Response: {"token": "..."}

# Use the token
curl http://localhost:7100/api/auth/me \
  -H 'Authorization: Bearer <token>'