Command-Line Interface (CLI)

The ml-dash CLI authenticates, queries, and manages projects and experiments on a remote server. Installed with the Python package:

bash

pip install ml-dash
ml-dash --help

Command	Description
`version`	Show ml-dash version
`login`	Authenticate via OAuth2 device flow
`logout`	Clear stored token
`profile`	Show current user
`api`	Send raw GraphQL queries/mutations
`list`	List projects, experiments, or tracks
`create`	Create a project

All commands accept --dash-url / --api-url (defaults to stored config or https://api.dash.ml) and --help.

`ml-dash version`

Print the installed version.

bash

ml-dash version

`ml-dash login`

Authenticate using the OAuth2 device authorization flow. Displays a URL, user code, and QR code; opens a browser; polls for authorization (10-minute timeout); stores the token in the system keychain.

bash

ml-dash login [--dash-url URL] [--auth-url URL] [--no-browser]

Flag	Description
`--dash-url`, `--api-url`	ML-Dash server URL
`--auth-url`	OAuth authorization server URL
`--no-browser`	Don't open the browser automatically

bash

ml-dash login --dash-url https://your-server.com

After login, all commands pick up the stored token; no --api-key flag needed.

`ml-dash logout`

Clear the stored token from the system keychain.

bash

ml-dash logout

`ml-dash profile`

Show the current authenticated user. By default fetches live data from the server; --cached reads only the stored token payload.

bash

ml-dash profile [--dash-url URL] [--json] [--cached]

Flag	Description
`--json`	Output as JSON
`--cached`	Use cached token data instead of fetching

Displays username, user ID, name, email, remote URL, and token expiration status.

bash

ml-dash profile --json

`ml-dash api`

Send raw GraphQL queries or mutations.

bash

ml-dash api (--query QUERY | --mutation MUTATION) [--jq PATH] [--dash-url URL]

Flag	Description
`--query`, `-q`	GraphQL query string
`--mutation`, `-m`	GraphQL mutation string
`--jq PATH`	Extract a value by dot-path (e.g. `.me.username`)

Notes:

Single quotes are auto-converted to double quotes.
--jq paths skip the top-level data key — use .me.username, not .data.me.username.
Bare bodies are auto-wrapped: me { username } becomes { me { username } }.

bash

ml-dash api --query "me { username }" --jq ".me.username"

`ml-dash create`

Create a new project. If the project already exists, the command exits successfully with a warning.

bash

ml-dash create -p PROJECT [-d DESCRIPTION] [--dash-url URL]

Flag	Description
`-p`, `--project`	`project` or `namespace/project` (required). Namespace auto-resolves from the authenticated user if omitted.
`-d`, `--description`	Project description

bash

ml-dash create -p tom/my-project -d "Baseline experiments"

`ml-dash list`

List projects, experiments, or tracks with server-side pagination (50 per page; navigate with n/→/Space for next, p/← for previous, any other key to quit).

bash

ml-dash list [-p PROJECT] [-n NAMESPACE] [--status STATUS] [--tags TAGS]
             [--detailed] [--tracks] [--topic-filter TOPIC]
             [--dash-url URL] [-v]

Flag	Description
`-p`, `--project`	Project filter. Supports glob patterns — always quote them to prevent shell expansion
`-n`, `--namespace`	Namespace (defaults to authenticated user)
`--status`	Filter by `COMPLETED`, `RUNNING`, `FAILED`, or `ARCHIVED`
`--tags`	Comma-separated tag filter
`--detailed`	Show tags and created time
`--tracks`	List tracks inside an experiment (requires full `namespace/project/experiment` path)
`--topic-filter`	Filter tracks by topic pattern (e.g. `robot/*`)
`-v`, `--verbose`	Show full error tracebacks

Glob patterns expand against the current namespace: tes* becomes {namespace}/tes*/*; tom/tes* becomes tom/tes*/*; fully-qualified patterns are left unchanged.

bash

# List your projects
ml-dash list

# Wildcard search (quote the pattern)
ml-dash list -p 'tom/tes*'

# Tracks inside an experiment, filtered by topic
ml-dash list --tracks -p tom/test/my-experiment --topic-filter "robot/*"

See Experiments and Metrics for working with the data these commands surface.

CI / scripting

Store the token in ~/.dash/config.json to skip login:

json

{
  "remote_url": "https://api.dash.ml",
  "api_key": "your-jwt-token"
}

If ml-dash isn't on PATH, run python -m ml_dash.cli or uv run ml-dash.