Skip to content

Authenticate the CLI

A muster that runs with oauth.server.enabled accepts requests only with a valid token. The muster CLI obtains that token through a browser login and keeps it for you. This guide covers the login, the contexts that hold endpoints, the authentication modes for scripts, where tokens live, and the exit codes.

Log in

muster auth login --endpoint https://muster.example.com/mcp

The CLI opens the browser at muster's authorization endpoint, muster redirects to Dex, and after the sign-in the tokens are stored locally. muster auth status shows the identity and how long the session lasts; muster auth whoami prints the identity alone.

The browser is the first command in $BROWSER that starts, else the platform default (xdg-open, open, start). --no-browser (env: MUSTER_NO_BROWSER=1) starts none: the CLI prints the authorization URL to stdout and waits for the callback until the URL is opened in any browser on the same machine, for example a tab an automated session drives. The environment variable applies to every command that signs in.

muster auth status
muster auth whoami
muster auth logout            # this endpoint
muster auth logout --all      # every stored token

A logout revokes the refresh and the access token at the revocation endpoint the server advertises in its OAuth metadata, then clears the stored token. When the server does not confirm the revocation, the stored token is cleared all the same and the command exits 1, saying that the server-side session stays valid until its tokens expire.

Every command that talks to the aggregator (list, get, call, create, start, stop, check, events, agent) uses the stored token and refreshes it when it expires. When no valid token exists, the default behaviour is to start the login in the browser before running the command.

Contexts

Contexts store endpoints under a name so that --endpoint is not repeated on every command. They live in ~/.config/muster/contexts.yaml.

muster context add prod --endpoint https://muster.example.com/mcp --use
muster context add staging --endpoint https://muster.staging.example.com/mcp
muster context list
muster context use staging
muster context current

The endpoint a command uses is resolved in this order:

  1. --endpoint
  2. --context <name>
  3. MUSTER_CONTEXT
  4. current-context in contexts.yaml
  5. http://localhost:8090/mcp

Tokens are stored per endpoint, so switching contexts switches identities as well.

Authentication modes

--auth (or MUSTER_AUTH_MODE) decides what happens when a command needs a token it does not have. A stored token is used and refreshed in every mode; the mode only decides whether a browser opens:

Mode Behaviour
none (default) Fail with exit code 2 and an auth_required error that names the login command; nothing interactive happens
auto Open the browser and complete the login, then run the command -- --login says the same
prompt Ask before opening the browser

The default is the mode for scripts, agents and CI: a missing login is a clear failure instead of a browser flow hanging inside a tool call. A person at a terminal adds --login:

muster call core_service_list --context gazelle          # auth_required, exit 2, no browser
muster call core_service_list --context gazelle --login  # opens the browser, then runs

Signing in to MCP servers behind muster

Some registered servers require their own login (a remote server with auth.type: oauth that does not accept muster's forwarded identity). muster auth login --server <name> completes that login for one server; muster auth login --all signs you in to muster and every server that is waiting for a login. Within an agent session the same is done with the core_auth_login tool, which returns the login URL for the server. muster auth logout and core_auth_logout revoke those grants.

Where tokens live

Tokens are written to ~/.config/muster/tokens/, one file per endpoint, with the file mode 0600 and the directory mode 0700; file names are hashes of the endpoint. A token file holds the access token, the refresh token, the expiry and the issuer. Tokens never appear in muster's logs; only hashed identifiers do.

The browser is redirected back to http://localhost:3000/callback. A browser resolves localhost to ::1 or 127.0.0.1, so muster auth login listens on port 3000 on both. When another process holds the port on either address, the login stops at once with callback port 3000 is already in use on [::1]:3000 by: and the holder's socket, pid and command line: stop that process, or pass --callback-port <port> (env: MUSTER_OAUTH_CALLBACK_PORT) when the server accepts a localhost redirect to another port.

Exit codes

Code Meaning
0 Success
1 Error: the command failed or its arguments were invalid
2 Authentication required and not available (no usable token and no --login, or the token could not be refreshed)
3 Authentication failed: the OAuth flow itself did not complete
125 self-update --check only: a newer release exists 
muster list mcpserver
case $? in
  0) ;;
  2) muster auth login ;;
  *) exit 1 ;;
esac