Skip to main content
Mesa never writes API tokens to config.toml. Tokens live in a secret store — a single backend you choose during onboarding or via config.toml under [secrets] backend = "...". Two backends are available:
  1. Encrypted file vault (encrypted-file) — age + scrypt at ~/.local/share/mesa/secrets.vault.age. Requires typing a passphrase each CLI session (or set MESA_VAULT_PASSPHRASE for non-interactive use). Default on fresh installs.
  2. Plaintext file (plaintext-file) — unencrypted TOML at ~/.local/share/mesa/secrets.plaintext.toml. For CI and ephemeral sandboxes only.

​
Configuring the backend

Set it in config.toml: 
[secrets]
backend = "encrypted-file"
Valid values: encrypted-file, plaintext-file. Default (fresh install): encrypted-file.

​
Registering a token

​
mesa auth set-key

The primary command. Scope is determined by the flags you pass; the key value is read from the positional argument or stdin. 
# Global token (falls back when nothing org-specific is set)
mesa auth set-key GLOBAL_TOKEN
# or pipe it
echo "$TOKEN" | mesa auth set-key

# Org-scoped
mesa auth set-key --org acme ACME_TOKEN
echo "$TOKEN" | mesa auth set-key --org acme

# Repo-scoped (overrides the org-scoped token for that repo)
echo "$TOKEN" | mesa auth set-key --org acme --repo web

​
MESA_ORGS environment variable

MESA_ORGS=<org>:<token>[,<org>:<token>...] registers tokens into the configured backend, then proceeds with the command. Useful for one-shot invocations from scripts and CI: 
MESA_ORGS=acme:$TOKEN mesa mount --daemonize

​
Onboarding wizard

On first run without any config, mesa probes platform capabilities and prompts you to pick a backend. The selection persists into config.toml. The wizard then prompts for org names and API tokens and writes them into the store.

​
Lookup order

When mesa needs a token for org <slug> (and optionally repo <name>):
  1. orgs/<slug>/repos/<name> — repo-scoped override.
  2. orgs/<slug> — org-scoped token.
  3. global — account-wide fallback.
  4. Otherwise: error no API key found in the secret store for organization '<slug>'.
Steps 1–2 are a single tree-walk in the store.

​
Choosing a backend

EnvironmentRecommended backend
Developer laptop (macOS / Linux desktop)encrypted-file (default)
Headless server you controlencrypted-file
CI runner / ephemeral sandboxplaintext-file
The plaintext-file backend writes tokens in plaintext to ~/.local/share/mesa/secrets.plaintext.toml. Only use it where the filesystem is ephemeral or otherwise already trusted (sandbox, short-lived VM).

​
CI / sandbox setup

In ephemeral environments, configure the plaintext backend and register the token via mesa auth set-key: 
# Write a minimal config
mkdir -p ~/.config/mesa
cat > ~/.config/mesa/config.toml <<'EOF'
mount-point = "/home/user/mesa/mnt"

[secrets]
backend = "plaintext-file"

[organizations.my-org]
EOF

# Register the token
mesa auth set-key --org my-org "$TOKEN"

# Mount
mesa mount --daemonize
Or do it in one shot with MESA_ORGS: 
MESA_ORGS=my-org:$TOKEN mesa mount --daemonize

​
Listing registered keys

mesa auth list-keys
Prints a tree of all stored tokens with masked values (mesa_****xxxx): 
global: mesa_****ab12
├── acme: mesa_****cd34
│   └── web: mesa_****ef56
└── initech
All stored keys are returned.

​
Removing a key

# Remove the org-scoped key for "acme"
mesa auth rm-key --org acme

# Remove a repo-scoped key
mesa auth rm-key --org acme --repo web

# Remove the global fallback key
mesa auth rm-key

​
Rotating tokens

Re-run mesa auth set-key with the new value — it overwrites the existing entry at that scope. To remove a token, use mesa auth rm-key.