Authentication

You log in once with the ml-dash CLI. The CLI saves a token on your machine, and both the CLI and the Python SDK read it from there. Local mode needs no login at all.

Log in

Install the CLI first (see Install), then:

ml-dash login

The CLI prints a short code and a QR code, and opens your browser at the approval page. Approve the request there. You never type a password into the terminal. Once you approve, the CLI saves the token and tells you where it put it, for example Your authentication token has been stored (keychain).

The code expires after 10 minutes. Check who you are logged in as, or log out:

ml-dash profile          # fetches your profile from the server
ml-dash profile --cached # reads the stored token only, no network
ml-dash logout           # clears the token from every place it could be stored

Where the token lives

The CLI stores the token in the most secure place the machine offers:

Set ML_DASH_NO_KEYCHAIN=1 before ml-dash login to skip the keychain and always use the encrypted file.

Using the token from Python

The SDK loads the stored token when an experiment has a dash_url. You don't pass any credentials in code:

from ml_dash import Experiment

with Experiment(prefix="alice/project/run-1", dash_url="https://api.dash.ml").run as exp:
    exp.log("Authenticated automatically")

The SDK reads the same places the CLI writes. If keyring is installed, it uses the OS keychain. Otherwise it uses ~/.dash/tokens.encrypted. So match the SDK install to where your login went:

• Token in the keychain (macOS, desktop Linux): install pip install "ml-dash[auth]", which adds keyring. Without it, the SDK can't see the token.
• Token in ~/.dash/tokens.encrypted: a plain pip install ml-dash reads it.

Servers and configuration

Both the CLI and the SDK default to https://api.dash.ml.

• CLI: --dash-url (alias --api-url) on any command, or remote_url in ~/.dash/config.json.
• SDK: the dash_url argument. dash_url=True uses the ML_DASH_API_URL environment variable, or https://api.dash.ml if it isn't set.

For scripts and CI, the CLI also accepts a token written directly into ~/.dash/config.json. It takes precedence over the stored login:

{
  "remote_url": "https://api.dash.ml",
  "api_key": "<token>"
}

The SDK does not read api_key from this file. It reads only the stored login described above.

How login works

ml-dash login uses the OAuth 2.0 Device Authorization Grant (RFC 8628) against auth.vuer.ai, then exchanges the result for an ML-Dash token:

ml-dash CLI                  auth.vuer.ai                   Browser
     |-- POST /api/device/start -->|                               |
     |   { device_secret_hash }    |                               |
     |<-- { user_code, verification_uri, expires_in: 600 }         |
     |  [prints code + QR, opens browser]                          |
     |                             |<-- user enters code, approves |
     |-- POST /api/device/poll --->|                               |
     |<-- 202 authorization_pending   (every 5 s)                  |
     |<-- 200 { access_token }     |                               |
     |                                                             |
     |-- POST /api/auth/exchange ──→ ML-Dash server                |
     |<-- { ML-Dash token }                                        |
  [stores the token]

• The poll is tied to a random per-machine secret, stored in ~/.dash/config.json. Only its SHA-256 hash is sent to the server, so there is no device_code that could be intercepted.
• The token from auth.vuer.ai is exchanged at the ML-Dash server's /api/auth/exchange for the token the CLI stores and the SDK sends.