Lettuce Docs Tags Graph

Keychain reset

#docs#troubleshooting#security
~3 min read

Keychain reset

When Lettuce’s Keychain entries get into a bad state, this is the unstick.

Symptoms

Diagnose

security find-generic-password -s com.lettuce.app

You should see entries. If you don’t, Keychain doesn’t have them. If you do but Lettuce can’t see them, the access control is wrong.

security find-generic-password -s com.lettuce.app -g

You’ll be prompted for your password. After auth, the entry’s metadata prints. Look at Access: it should be Lettuce.app (or Always for headless usage).

The nuclear option

Agent keys are managed with lettuce keys, which has exactly three subcommands: list, add, and remove. There is no bulk reset, so to clear everything, remove each key by label:

lettuce keys list
lettuce keys remove --label <label>

You’ll then need to:

  1. Re-create agent keys with lettuce keys add --label <label> (and reconfigure each agent client with the new token).

  2. Re-paste provider keys (Anthropic, OpenAI, etc.) in Settings → AI providers, or re-export the provider env vars (ANTHROPIC_API_KEY, OPENAI_API_KEY, etc.).

  3. Re-supply the deploy token (--token or $GITHUB_TOKEN) the next time you run lettuce deploy.

Surgical fixes

Remove one stuck entry

lettuce keys remove --label <label>

Where <label> is from lettuce keys list. The token stops working immediately; create a fresh one with lettuce keys add --label <label>.

Fix access control

security set-generic-password-partition-list \
  -S apple-tool:,apple:,unsigned: \
  -s com.lettuce.app

This re-grants Lettuce’s signing certificate access. Useful after upgrading Lettuce when the certificate identity changes.

Keychain Access UI

Open Keychain Access.app → Login → search for com.lettuce. Right-click an entry → Access Control → make sure Lettuce.app is in the allowed list.

Provider key issues

Provider keys are not managed by lettuce keys (that command only manages scoped agent keys). They come from the GUI’s Settings → AI providers, or from environment variables such as ANTHROPIC_API_KEY / OPENAI_API_KEY.

If an agent invocation reports an invalid provider key:

  1. The stored secret has been corrupted — re-paste it in Settings → AI providers, or re-export the matching env var.

  2. The provider revoked the key — visit the provider’s dashboard.

  3. Network — check curl -I https://api.anthropic.com/.

Deploy credential issues

There is no stored deploy credential to reset; lettuce deploy reads the GitHub token from the --token flag or the $GITHUB_TOKEN environment variable on each run. If a deploy fails with an auth error:

GITHUB_TOKEN=<your-pat> lettuce deploy <vault> --repo <user>/<repo>

Make sure the PAT is current and has repo write access.

A pattern that comes up

After a clean macOS install and a Time Machine restore, Keychain often comes back but Application Support folders are merged from multiple sources. Lettuce’s Keychain entries are tied to the restored Keychain but Application Support paths may be inconsistent.

Fix: Reset Keychain entries (above), then re-pair agents. The bundled docs vault regenerates itself on next launch, so there’s nothing to reset there by hand.