CLI authentication

Set the hosted API before signing in:

brainmaps config set-api-url https://api.brainmaps.xyz
brainmaps login

The command prompts for email and password and saves the returned token in ~/.brainmaps/config.json. brainmaps signup creates an account and signs in; uploading and other contribution workflows still require account approval.

Use a personal access token

Create a token in the website’s account settings, or with an authenticated CLI:

brainmaps token create "Lab workstation"
brainmaps token list

For automation, inject BRAINMAPS_API_KEY from your environment or secret manager. It takes precedence over the saved token. The CLI does not automatically load a project’s .env file.

To save an existing token locally:

brainmaps token register "$BRAINMAPS_API_KEY"

The API header is Authorization: Token YOUR_TOKEN, not Bearer. See token reference for expiry and revocation.

Sign out or revoke access

brainmaps logout
brainmaps token revoke TOKEN_UUID

Run revocation while authenticated with another valid token if you have already logged out. Logout revokes the token used for that request and clears the saved local token; it does not revoke every token on your account. If BRAINMAPS_API_KEY is set, unset it as well when you finish.

Troubleshooting

• Wrong account or API: check brainmaps config get-api-url and whether BRAINMAPS_API_KEY overrides the saved login.
• Read works but upload is forbidden: your account may still need approval. Signing in is sufficient to read platform data, but not to perform every write.
• Expired or revoked token: log in again or register a replacement. Commands do not automatically open a login screen on failure.
• Species/category permission errors: signed-in users can add species through the website or API. Only the superadmin can edit categories or existing species.

See the platform permission table.