CLI Authentication

The MyClaude CLI authenticates via Firebase Auth REST API, stores refresh tokens in the OS keychain, and never writes session tokens to disk.

This guide covers the full authentication lifecycle: logging in, how tokens are stored and refreshed, non-interactive authentication for CI/CD, session management, and troubleshooting.

How authentication works

The CLI uses Firebase Authentication as its identity layer -- the same system that powers the MyClaude web application. When you run myclaude login, the following sequence occurs:

1. The CLI prompts for your email and password (password input is masked).
2. It calls the Firebase Auth REST API to exchange your credentials for a refresh token and a short-lived ID token.
3. The refresh token is stored in your operating system's keychain (macOS Keychain, Windows Credential Manager, or Linux Secret Service).
4. Non-sensitive metadata (your UID, email, username, and the public API key) is written to ~/.myclaude/config.json.
5. The ID token is held in memory for the duration of the command and then discarded. It is never written to disk.

Every subsequent command that requires authentication reads the refresh token from the keychain, exchanges it for a fresh ID token via Firebase's token refresh endpoint, and uses that ID token for API calls. This happens transparently -- you will not see any "refreshing token" messages unless the refresh fails.

Logging in

Run myclaude login from any terminal:

$ myclaude login
# Email: you@example.com
# Password: ********
# Authenticated as @your-username (you@example.com)

On success, the CLI prints your username and email, then stores your session. You are now authenticated for all commands that require it.

If you have not yet created a MyClaude account, register at myclaude.sh first. The CLI does not support account creation.

What gets stored

The refresh token is stored under the service name vault-marketplace in your OS keychain. On systems where the keychain is unavailable, the CLI falls back to a file at ~/.myclaude/credentials with chmod 600 permissions and prints a warning recommending keychain setup.

Token lifecycle

Refresh tokens

Refresh tokens have a 90-day hard expiry from the time of issue and a 10-day idle timeout. If you do not use the CLI for 10 consecutive days, the refresh token expires and you must run myclaude login again.

During normal use, the refresh token is silently exchanged for a fresh ID token on every command invocation. This exchange also resets the idle timeout, so active CLI users never encounter expiry during regular workflows.

ID tokens

ID tokens are short-lived (1-hour expiry) and exist only in process memory. They are obtained from the refresh token at the start of each CLI invocation and used for all API calls during that invocation. When the command exits, the ID token is gone.

This design ensures that even if an attacker gains read access to your filesystem, there is no usable session token on disk to steal.

Token refresh flow

Command invoked
  -> Read config.json (get API key)
  -> Read refresh token from keychain
  -> POST to Firebase token refresh endpoint
  -> Receive fresh ID token (1h expiry)
  -> Use ID token for all API calls
  -> Command exits, ID token discarded

If the refresh fails (token expired, revoked, or network error), the CLI clears stored credentials and prompts you to log in again:

$ myclaude search "code review"
# Error: session expired. Run myclaude login to re-authenticate.

Non-interactive authentication for CI/CD

In CI/CD environments where interactive login is not possible, use the --token flag or the MYCLAUDE_TOKEN environment variable to provide a pre-generated API token:

# Using the --token flag
$ myclaude login --token eyJhbGciOiJSUzI1NiJ9...
# Authenticated as @your-username

# Using the environment variable
$ export MYCLAUDE_TOKEN=eyJhbGciOiJSUzI1NiJ9...
$ myclaude publish --dry-run
# (uses MYCLAUDE_TOKEN for authentication)

When MYCLAUDE_TOKEN is set, the CLI skips the keychain entirely and uses the provided token directly. This is the recommended approach for CI/CD pipelines. Store the token as a secret in your CI provider (GitHub Actions secrets, GitLab CI variables, etc.) and inject it at runtime.

To generate a token for CI/CD use, log in interactively on a trusted machine and extract the refresh token. Scoped tokens with limited permissions are planned for a future release.

CI/CD example with GitHub Actions

name: Publish to MyClaude
on:
  push:
    tags: ["v*"]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
      - run: npm install -g @myclaude-cli/cli
      - run: myclaude publish
        env:
          MYCLAUDE_TOKEN: ${{ secrets.MYCLAUDE_TOKEN }}

Session management

Check current session

$ myclaude whoami
# Logged in as @your-username

myclaude whoami makes a lightweight API call to verify the stored token is still valid. It returns exit code 0 on success and exit code 2 if no valid session exists. Use this in scripts to gate operations on an authenticated state:

$ myclaude whoami || myclaude login

Log out

$ myclaude logout
# Logged out. Credentials removed.

myclaude logout deletes the refresh token from the OS keychain and removes ~/.myclaude/config.json. No network request is made -- the logout is local only. Sessions on other devices are not affected.

Verify then act

A common pattern: verify authentication before running a pipeline.

$ myclaude whoami && myclaude publish

If whoami returns a non-zero exit code, the shell short-circuits and publish does not run.

Multiple accounts

The CLI supports one active session at a time. To switch between accounts, log out and log back in:

$ myclaude logout
$ myclaude login
# Email: other-account@example.com
# Password: ********
# Authenticated as @other-account

If you frequently switch between accounts (for example, a personal account and an organization account), consider using shell aliases or environment-specific MYCLAUDE_TOKEN values to manage separate credentials.

Security considerations

Tokens never leave your machine. The CLI communicates only with Firebase Auth endpoints and the MyClaude API over HTTPS. Your refresh token is never sent to any third-party service.

Keychain encryption. On macOS, the refresh token is stored in the macOS Keychain, encrypted with your login password. On Windows, it uses Credential Manager. On Linux, it uses the Secret Service API (typically backed by GNOME Keyring or KWallet).

No plaintext passwords. Your email and password are transmitted to Firebase Auth over HTTPS and are never stored locally. Only the resulting tokens are persisted.

Credential file fallback. If the OS keychain is unavailable (common in headless servers or containers), the CLI writes the refresh token to ~/.myclaude/credentials with chmod 600 and prints a warning. In these environments, prefer MYCLAUDE_TOKEN over the file fallback.

Troubleshooting authentication

Related pages

• CLI Installation -- install the CLI and run your first login
• CLI Commands Reference -- full reference for login, logout, and whoami
• CLI Configuration -- environment variables and config file settings
• CLI Troubleshooting -- broader FAQ covering all CLI issues