Authentication

Every command except --help needs a bearer token. There are three ways to supply one, checked in this order:

1. --token on the command
2. Stored credentials, selected by --alias
3. The POLYMESA_TOKEN environment variable

Browser login

The usual path for a human at a terminal. It opens your browser, you sign in, and the CLI stores the resulting token.

polymesa auth login --url https://api.polymesa.com

Nothing to copy and paste, and no password touches your shell history.

Password login

For environments with no browser. Prints the JWT to stdout rather than storing it.

polymesa login --email you@example.com --password 'hunter2' --url https://api.polymesa.com

Caution

--password on the command line lands in your shell history and is visible in ps output to other users on the machine. Prefer polymesa auth login, or a connected app for anything automated.

Connected apps (machine-to-machine)

For CI and scripts, use the JWT bearer flow with an RSA key rather than a password. No interactive step, no user credentials.

polymesa auth login \
  --jwt \
  --client-id <client-id> \
  --key-file ./private-key.pem \
  --username service@example.com \
  --url https://api.polymesa.com

The CLI signs an assertion with your private key and exchanges it for a token. The private key never leaves your machine.

Aliases

Credentials are stored under named aliases, so one machine can talk to several instances — production, staging, a local stack — without re-authenticating.

# Store under a name
polymesa auth login --alias prod --url https://api.polymesa.com
polymesa auth login --alias local --url http://localhost:3000

# Use one
polymesa retrieve ./config --alias prod

# Inspect
polymesa auth list
polymesa auth whoami --alias prod

# Remove
polymesa auth logout --alias local
polymesa auth logout --all

Commands default to the default alias when --alias is omitted.

Where credentials live

Tokens are written to ~/.polymesa/credentials.json (%USERPROFILE%\.polymesa\ on Windows) as JSON:

{
  "defaultAlias": "prod",
  "instances": {
    "prod": { "...": "..." }
  }
}

Not encrypted

The file holds bearer tokens in plaintext, protected only by filesystem permissions. Treat it like ~/.aws/credentials: do not commit it, do not copy it between machines, and revoke tokens if a machine is compromised.

Workspaces

On a multi-workspace account, each alias has a default workspace. Override it per command without switching alias:

polymesa retrieve ./config --alias prod --workspace acme
polymesa auth whoami --alias prod --workspace acme

Environment variables

Useful in CI, where flags get unwieldy:

Variable	Purpose
POLYMESA_TOKEN	Bearer token, used when no --token or alias applies
POLYMESA_API_URL	Default API base URL, replacing --url

export POLYMESA_API_URL=https://api.polymesa.com
export POLYMESA_TOKEN="$(cat token.txt)"

polymesa deploy ./config

Without either, the API URL defaults to http://localhost:3000.