03.
— Section 3
Credentials
macOS Keychain
Your password never touches disk.
jmapcli keeps no secret on disk. Your password (or bearer token) lives in the macOS login Keychain; the account file — ~/.config/jmapcli/config.json, mode 0600 — holds only the server URL, your username and a default flag. New to the Keychain from the terminal? The whole workflow is three built-in security commands.
1 · Store a secret — and read it back. macOS prompts for the value, so the secret is never typed on the command line, shown on screen, or written to your shell history.
# store it — you’re prompted for the secret, nothing echoes
$ security add-generic-password -U -s jmap-password -a you@example.com -l "Boogie JMAP password" -w
# read it back at any time
$ security find-generic-password -s jmap-password -a you@example.com -w
# remove it
$ security delete-generic-password -s jmap-password -a you@example.com
- -s
- service — the name jmapcli looks up: jmap-password for a password, or jmap-token for a bearer token (e.g. Fastmail); set only the one you use.
- -a
- account — your email address (the same username you give jmapcli).
- -l
- label — what you’ll see in the Keychain Access app; -U updates an existing item in place.
- -w
- with no value — prompt for the secret. This is the part that keeps it out of ~/.zsh_history and the process list.
2 · Point jmapcli at your server. Register the account once; the secret is pulled straight from the Keychain item you just stored, so it never appears on the command line.
$ jmapcli login --url https://mail.example.com --username you@example.com \
--password "$(security find-generic-password -s jmap-password -a you@example.com -w)"
# token auth: swap --password for --token (and store under jmap-token above)
$ jmapcli list # from here on, every command reads the Keychain for you
# OAuth — no app password to create, copy, or rotate.
# Your browser opens once; the token lands in the Keychain under jmap-oauth.
$ jmapcli login --url https://api.fastmail.com --username you@fastmail.com --oauth
# Stalwart — or any server that speaks RFC 8252 — same flag.
$ jmapcli login --url https://mail.example.com --username you@example.com --oauth
3.1
Nothing in your history, logs — or an AI’s context
Once the secret is in the Keychain, everyday commands (list, send, draft, sync) never carry a password, so it can’t be captured in ~/.zsh_history, a process listing or CI logs. That is what makes jmapcli safe to drive from terminal-AI tools — an agent is handed a JMAP client, never your secret.
— zsh
CI · agents
3.2
Rotate or sign out
Changed your password? Re-run the security add-generic-password … -w line — -U overwrites it in place. To remove an account, jmapcli logout deletes both the config entry and the Keychain secret in one step (--all clears every account).
— rotate
logout
3.3
Per-Mac by design
The login Keychain isn’t synced through iCloud — a deliberate boundary, so your password never leaves the Mac you typed it on. Repeat the security step once per Mac; config.json can ride a synced home folder because it carries no secret.
— per
machine
Boogie