ML-Dash

CLI Reference

The ml-dash command logs you in, inspects projects and experiments, and moves experiment data to and from an ML-Dash server. This page covers the @dreamlake/ml-dash 0.3.0 and its existing standalone commands.

The CLI is a separate program from the Python SDK. Install it with the standalone installer or npm install -g @dreamlake/ml-dash (see Install). pip install ml-dash no longer installs it (since SDK 0.7.0).

CommandDescription
loginAuthenticate with the OAuth device flow
logoutClear the stored token
profileShow the current user and configuration
listList projects, experiments, and tracks on the server
createCreate a project
removeDelete a project and everything in it
uploadUpload locally stored experiments to the server
downloadDownload experiments from the server to local storage
apiSend a raw GraphQL query or mutation
updateUpdate the CLI itself
versionPrint the CLI version

The 0.3.0 management surface below requires matching enabled DreamLake and Dash managed services. Run ml-dash version and ml-dash instance capabilities --json to inspect the installed client and server separately. Capability metadata is not a running binary version.

Run ml-dash <command> --help for the exact flags of your installed version.

CLI 0.3.0 and SDK 0.11.0 are publicly available. Schema inspection and pagination require matching server contracts. Compute job reporting additionally requires a reporting-enabled Nymph 0.1.28 worker; that version is an explicit artifact, not an automatic worker upgrade. CLI installation grants no host execution rights. Production compute acceptance remains deferred.

Managed administration command map

Management commands use DreamLake authority by default. The top-level commands in the first table retain standalone Dash behavior. Do not interchange their credentials. Explicit --standalone supports only the existing standalone API operations described below; it does not convert managed setup or credentials.

Command groupAccepted actions
authstatus, login
instanceshow, capabilities
orgslist, create, update, delete, members, teams, member-add, member-role, member-remove
projectslist, access
teamslist, members (standalone diagnostics)
setupplan, apply, status, resume
credentialslist, inspect, create, rotate, retire
runslist, show, create, status, parameters, delete
metricslist, read, append
logsread, append
fileslist, inspect, upload, download
health, diagnosticscheck
connectionslist
workspaceslist, status, plan, apply, detach
adoptioninventory, plan, apply, reconcile, recover

projects access reports effective access; it does not grant permissions. There are no new projects create/update/delete management actions: existing standalone create/remove remain available, and managed setup selects an existing DreamLake project. DreamLake organization deletion currently returns OWNERSHIP_LIFECYCLE_UNSUPPORTED rather than pretending to implement retention.

Management options

OptionsPurpose
--namespace, --projectExplicit DreamLake organization and project selection
--dreamlake-urlBFF matching the existing shared DreamLake login
--standalone, --dash-url, --api-urlExplicit separate Dash authority and server
--run, --run-key, --metric, --fileStable resource IDs, run creation key or exact metric name
--name, --description, --user, --role OWNER/MEMBERReviewed organization metadata or explicit membership target
--limit, --cursorBounded pages and opaque continuation cursor
--offset, --teamStandalone list continuation and team diagnostics
--data FILE, --input FILE, --content-typeJSON workload input or file attachment; --data - reads stdin
--status, --mode read/writeRun status or session mode; status accepts RUNNING/COMPLETED/FAILED/CANCELLED
--credential, --expected-generationScoped writer metadata and reviewed generation
--out, --review, --apply, --idempotency-keyNon-secret exact review/receipt, explicit apply and stable intent
--connection, --remote-namespaceOperator-approved external alias and verified namespace
--remote-project, --expected-revision, --plan-hashExplicit legacy adoption target and authority review
--json, --no-browser, --auth-urlStructured output or managed device login options

Options are parsed across management groups but apply only to their documented actions. --mode does not expand project permission or grant a delete capability.

Managed workflows and recovery

Login, identity and discovery

Managed commands use the existing DreamLake ~/.dreamlake/config.json and tokens.json slots. They do not reuse or copy a standalone Dash token. An explicit auth login runs the existing Vuer dreamlake-app device flow and DreamLake /auth/exchange, validates /auth/me, and materializes the shared DreamLake user login. It preserves other config settings. Scoped workload tokens are acquired in memory for one operation, never written or printed. The top-level login command continues to serve standalone Dash.

sh
ml-dash auth status --json
ml-dash auth login --no-browser --json
ml-dash instance show --json
ml-dash orgs list --limit 50 --json
ml-dash orgs members --namespace fortyfive --json
ml-dash projects list --namespace fortyfive --limit 50 --json
ml-dash projects access --namespace fortyfive --project research-harness --json

--dreamlake-url selects the BFF, not an arbitrary Dash server. An existing credential is sent only to its matching configured server; changing the URL does not forward an old login. HTTPS is required except for loopback test endpoints. DREAMLAKE_REMOTE and DREAMLAKE_API_KEY support explicit existing environments; no command accepts a token argument. ML_DASH_MANAGED_CONFIG_DIR selects an isolated shared-login directory for tests or an explicit alternate environment.

Namespace/project/credential pages retain opaque nextCursor values. Repeat the same list with --cursor to continue. Exact project/run/file selection traverses bounded cursor pages, fails on repeated cursors, and never calls the first page complete. CLI 0.2.0 managed member inspection used an unpaged typed GraphQL response. In CLI 0.3.0, orgs members and orgs teams use organizationMembersPaginated and organizationTeamsPaginated on matching servers, with --limit (1–100) and --offset. Preserve nextOffset, hasMore and totalCount; these offset lists refuse opaque --cursor. Member mutations review the complete bounded paginated inventory and stop if counts or continuation change. Client-side slicing is not server pagination.

By default all these management commands use DreamLake authority. Explicit --standalone uses the separate Dash config and login; neither credential is forwarded to the other system. Standalone organization/member/team lists use the companion paginated GraphQL queries with --limit and --offset/nextOffset. teams list|members --standalone is diagnostic inspection; team membership is not a project data ACL. Standalone instance inspection reads /.well-known/dash-experiments, which exposes protocol/capability enablement, not an invented running binary version.

Organization create/update actions use typed GraphQL and exact reviewed metadata. DreamLake organization deletion is intentionally disabled with OWNERSHIP_LIFECYCLE_UNSUPPORTED; resource/secret retention manifests are absent. Standalone orgs delete --standalone requires the companion server's advertised transactional empty-only soft-delete capability, refuses visible projects, and relies on the server to atomically include soft-deleted projects in its guard. It never calls an old hard-delete implementation.

Organization member add/role/remove actions require an OWNER and a reviewed snapshot of the current membership. Use explicit user IDs and roles, never a name guess. These update DreamLake only; no Dash memberships are copied or unioned.

sh
ml-dash orgs member-add --namespace fortyfive --user USER_ID --role MEMBER --out member-review.json --json
ml-dash orgs member-add --namespace fortyfive --user USER_ID --role MEMBER --apply --review member-review.json --json

Machine-readable inspection (0.3.0)

CLI 0.3.0 exposes these local and server inspection commands:

sh
ml-dash schema --json
ml-dash instance schema --schema-version 1 --json
ml-dash orgs members --namespace fortyfive --limit 50 --offset 0 --json
ml-dash orgs teams --namespace fortyfive --limit 50 --offset 0 --json

schema is offline and needs no login. It derives command names, actions, option aliases/types/enums, positionals and required arguments from the actual dispatch registry. Per-action contracts identify authority, pagination and review/apply requirements. Legacy output remains command-specific; it is not described as a managed success/error envelope.

instance schema uses the shared DreamLake login and reads /managed-experiments/schema?version=1. It returns separate cli and server sections with package, schema and managed protocol versions plus actual operation input/output JSON Schemas. Unknown schema/protocol versions or metadata without required schemas fail closed. Capability discovery alone, GraphQL introspection and an invented running binary version cannot substitute for this contract. Use the offline schema to inspect local command availability.

Setup: exact preview, receipt and recovery

sh
ml-dash setup plan --namespace fortyfive --project research-harness --out setup-review.json --json
# Review stable namespace/project/instance IDs, resources, revision and planHash.
ml-dash setup apply --namespace fortyfive --project research-harness --apply --review setup-review.json --idempotency-key SETUP_INTENT_ID --out setup-receipt.json --json
ml-dash setup status --namespace fortyfive --project research-harness --json

The CLI submits only the reviewed expectedRevision, planHash and stable idempotencyKey; the server owns actual provisioning and a durable receipt. setup plan makes only reads. A changed review is refused. Review and receipt files use exclusive creation and contain no tokens. Retain both after success.

If a response is lost, inspect status before retrying. Reuse the same review and intent key with setup resume; it replays the original intent rather than substituting the latest revision or a different target. The server validates that replay against its durable receipt. An unrelated owner or changed resource cannot silently win the retry. The CLI validates the returned receipt's stable namespace/project/instance IDs, revision and intent key.

sh
ml-dash setup resume --namespace fortyfive --project research-harness --apply --review setup-review.json --idempotency-key SETUP_INTENT_ID --json

Scoped workload credentials and logging

Credential commands expose metadata only. create requires a stable UUID intent key; rotation and retirement require the currently reviewed generation. Workload credential management is limited to the actual requester; an organization role does not silently adopt another person's writer. The server controls expiry, revocation and current project authorization on renewal. Already issued capabilities may remain usable for the documented short TTL plus clock skew.

sh
ml-dash credentials list --namespace fortyfive --project research-harness --json
ml-dash credentials create --namespace fortyfive --project research-harness --run RUN_ID --idempotency-key UUID_INTENT --out writer-review.json --json
ml-dash credentials create --namespace fortyfive --project research-harness --run RUN_ID --idempotency-key UUID_INTENT --apply --review writer-review.json --json
ml-dash credentials inspect --namespace fortyfive --project research-harness --credential WRITER_ID --json
ml-dash credentials rotate --namespace fortyfive --project research-harness --credential WRITER_ID --expected-generation 1 --out rotate-review.json --json
ml-dash credentials rotate --namespace fortyfive --project research-harness --credential WRITER_ID --expected-generation 1 --apply --review rotate-review.json --json

Use retire with the same review/apply pattern to revoke future use/renewal. There is no export-token command. A first write can use a stable UUID --idempotency-key; a known writer uses --credential WRITER_ID. Returned workload metadata includes the writer ID, generation and expiry, never its token. A run-scoped writer can write only its bound run. Reads use the BFF, preserving current DreamLake authorization.

sh
ml-dash runs create --namespace fortyfive --project research-harness --run-key training-001 --idempotency-key UUID_INTENT --out run-review.json --json
ml-dash runs create --namespace fortyfive --project research-harness --run-key training-001 --idempotency-key UUID_INTENT --apply --review run-review.json --json
ml-dash runs list --namespace fortyfive --project research-harness --json
ml-dash runs show --namespace fortyfive --project research-harness --run RUN_ID --json
ml-dash metrics list --namespace fortyfive --project research-harness --run RUN_ID --json
ml-dash metrics read --namespace fortyfive --project research-harness --run RUN_ID --metric loss --limit 100 --json
ml-dash logs read --namespace fortyfive --project research-harness --run RUN_ID --limit 100 --json
ml-dash files list --namespace fortyfive --project research-harness --run RUN_ID --json

metrics append accepts --data points.json as a 1–1000-point JSON array. logs append accepts 1–1000 log entries; each contains timestamp, level and message. runs parameters accepts a JSON object; runs status --status COMPLETED updates lifecycle status. runs parameters without --data reads current parameters. runs delete requires its own exact preview/apply and acquires a separate capability whose only action is delete; ordinary writer sessions are not expanded. It soft-deletes the experiment record while retaining underlying logs, metrics, parameters and files. Each write uses the same default-preview then --apply --review pattern. A saved workload review binds stable resources, operation, credential intent and payload hash. Changing input after approval is refused before acquiring a scoped session. Non-idempotent log/metric append is not automatically retried after an unknown network outcome.

Managed file upload is files upload --input ./artifact.txt, with the same review pattern. It supports one flat filename and at most 8 MiB per attachment; this is the managed API limit, not a new limit on standalone streaming upload/download. The CLI never prints base64 payloads. Download uses a user-selected path:

sh
ml-dash files download --namespace fortyfive --project research-harness --run RUN_ID --file FILE_ID --out ./artifact-copy.txt --json

Download verifies byte count and SHA-256 before atomically installing the file, ignores a server-supplied filename as a path, and refuses an existing destination. No presigned or persistent storage credential is exported.

Diagnostics and advanced external workspaces

sh
ml-dash health check --json
ml-dash diagnostics check --namespace fortyfive --project research-harness --json
ml-dash connections list --namespace fortyfive --json
ml-dash workspaces list --namespace fortyfive --connection APPROVED_ALIAS --json
ml-dash workspaces status --namespace fortyfive --json
ml-dash workspaces plan --namespace fortyfive --connection APPROVED_ALIAS --remote-namespace REMOTE_ID --out external-review.json --json
ml-dash workspaces apply --namespace fortyfive --connection APPROVED_ALIAS --remote-namespace REMOTE_ID --apply --review external-review.json --json

Managed setup is the default path; external connection management is advanced. Only operator-approved aliases are accepted. Discovery verifies the external instance and eligible workspace. No URL/token is supplied by the user, and equal organization names never establish a mapping.

In CLI 0.3.0, connections list and workspaces list accept --limit (1–100) and opaque --cursor, preserving hasMore and nextCursor. Repeat with the same limit to continue. Workspace selection for plan/apply starts at page zero, traverses at most 100 pages, and verifies the exact immutable namespace ID. It refuses caller-supplied selection cursors, repeated cursors, duplicate IDs, non-progress and instance drift rather than silently selecting from page one. Dash filters live organization namespaces and current OWNER membership in the database before limiting results. Discovery grants no data access; binding verification rechecks ownership. CLI 0.2.0 does not contain this complete traversal improvement. Applying pins the reviewed instance/namespace/alias and current binding revision. workspaces detach previews by default and applies with the same saved-review pattern. Detachment is local, retains remote data, and does not depend on external discovery.

Legacy project adoption

adoption inventory reads the explicit legacy project; adoption plan requests a server-generated exact plan against its current authority revision. The BFF owns separate requester/legacy-owner checks and adoption authorization. A normal managed writer is never an adoption credential.

sh
ml-dash adoption inventory --namespace fortyfive --project research-harness --remote-project LEGACY_PROJECT_ID --json
ml-dash adoption plan --namespace fortyfive --project research-harness --remote-project LEGACY_PROJECT_ID --expected-revision REMOTE_REVISION --out adoption-review.json --json
ml-dash adoption apply --namespace fortyfive --project research-harness --remote-project LEGACY_PROJECT_ID --apply --review adoption-review.json --idempotency-key ADOPTION_INTENT --json
ml-dash adoption reconcile --namespace fortyfive --project research-harness --remote-project LEGACY_PROJECT_ID --plan-hash PLAN_HASH --json

Apply replaces authority according to the reviewed policy rather than unioning old and new memberships. It requires operator fencing, backup and write draining; it is disabled until those server preconditions are provided. A precondition error is a real blocker, never a successful adoption. Recovery uses the same review, --expected-revision from current authority and a stable intent key. No CLI flag enables server fencing or bypasses these safeguards.

Output and backend mapping

All commands offer --json: success is {ok:true,data}, failure is {ok:false,error:{code,message,remediation,retryable}} with nonzero exit status. Human output contains the same non-secret data, plus a concise status. Upstream raw error bodies, login tokens, scoped tokens and file base64 are excluded.

SurfaceActual API
Login/statusVuer device start/poll; DreamLake /auth/exchange, /auth/me
Instance/discoveryBFF /managed-experiments/capabilities, /namespaces, /ns/:ns/projects
Organization membershipFixed typed DreamLake GraphQL operations; no user-supplied query
Setup/statusBFF project /setup, /status with durable CAS/intent receipt
CredentialsBFF project /credentials, /credentials/:id; scoped /session only in memory
ReadsBFF project /runs, metrics/logs/files and verified file download
WritesDash /api/managed/projects/:stableId/runs/... with short scoped session
External workspacesBFF /integrations/dash/ns/:ns/connections, /workspaces, /binding
AdoptionBFF project /adoption/:legacyProjectId/{inventory,plan,apply,reconcile,recover}

Standalone common options

FlagDescription
--dash-url, --api-url URLServer to talk to. Defaults to remote_url in ~/.dash/config.json, then https://api.dash.ml. Accepted by every command that contacts the server.
-h, --helpShow help for the command

ml-dash login

bash
ml-dash login [--dash-url URL] [--auth-url URL] [--no-browser]
FlagDescription
--dash-url, --api-urlML-Dash server to log in to
--auth-urlOAuth authorization server (default https://auth.vuer.ai)
--no-browserPrint the code and URL, but don't open a browser

Starts the device authorization flow. It prints a code, a URL, and a QR code, waits up to 10 minutes for you to approve in a browser, exchanges the result for an ML-Dash token, and stores it. See Authentication for where the token goes and how the SDK reads it.

ml-dash logout

bash
ml-dash logout

Clears the stored token from the keychain and from the ~/.dash/ token files.

ml-dash profile

bash
ml-dash profile [--dash-url URL] [--json] [--cached]
FlagDescription
--jsonOutput as JSON
--cachedRead the stored token only, without fetching from the server

Shows your username, name, email, server URL, token expiry, and whether the data came from the server or the cached token.


ml-dash list

bash
ml-dash list [-p PROJECT] [-n NAMESPACE] [--status STATUS] [--tags TAGS]
             [--detailed] [--tracks] [--topic-filter TOPIC] [--dash-url URL] [-v]
FlagDescription
-p, --project (aliases --prefix, --pref, --proj)List experiments in this project. Without it, lists projects. Accepts glob patterns: always quote them, e.g. -p 'tom/tut*'
-n, --namespaceNamespace for all queries. Defaults to your own
--statusFilter experiments: COMPLETED, RUNNING, FAILED, or ARCHIVED
--tagsFilter experiments by tags (comma-separated)
--detailedShow more columns
--tracksList the tracks in one experiment. Needs -p namespace/project/experiment
--topic-filterFilter tracks by topic, e.g. 'robot/*'
-v, --verboseVerbose output

Results come 50 per page. In a terminal, move between pages with n / → / Space / Enter (next) and p / b / ← (previous). Any other key quits. When output is piped, list prints the first page and notes that more results are available.

A glob without a namespace is expanded against your own namespace:

InputSearches
tes*<your-namespace>/tes*/*
tom/tes*tom/tes*/*
tom/test/exp*tom/test/exp*
bash
ml-dash list                                   # your projects
ml-dash list -n alice                          # alice's projects
ml-dash list -p my-project                     # experiments in a project
ml-dash list -p 'tom/tes*' --status RUNNING    # glob across projects
ml-dash list --tracks -p tom/test/run-1 --topic-filter 'robot/*'

ml-dash create

bash
ml-dash create -p PROJECT [-d DESCRIPTION] [--dash-url URL]
FlagDescription
-p, --projectproject or namespace/project. Without a namespace, your own is used
-d, --descriptionOptional description

If the project already exists, create prints a warning and exits successfully.

ml-dash remove

bash
ml-dash remove -p PROJECT [-y] [--dash-url URL]
FlagDescription
-p, --projectproject or namespace/project
-y, --yesSkip the confirmation prompt

remove deletes the project and all of its experiments, metrics, files, and logs. It cannot be undone.


ml-dash upload

bash
ml-dash upload [PATH] [options]

Uploads experiments that the SDK wrote in local mode. PATH is the local storage directory and defaults to ./.dash.

FlagDescription
-p, --project (aliases --prefix, --pref, --proj)Only upload experiments matching this prefix or glob, e.g. 'tom/*/exp*'
-t, --targetUpload under this prefix on the server instead, e.g. alice/shared-project
--skip-logs, --skip-metrics, --skip-files, --skip-paramsLeave that kind of data out
--dry-runShow what would be uploaded without uploading
--strictFail on any validation error. By default, invalid data is skipped
--batch-size NBatch size for logs and metrics (default 100)
--resumeResume an interrupted upload
--state-file FILEState file for --resume (default .dash-upload-state.json)
--tracks FILEUpload a single track data file (e.g. robot_position.jsonl). Needs --remote-path
--remote-path PATHWhere the track goes, e.g. namespace/project/exp/robot/position
-v, --verboseShow detailed progress
bash
ml-dash upload                                  # everything in ./.dash
ml-dash upload ./.dash -p 'tom/*/exp*'          # a subset
ml-dash upload --dry-run -v                     # preview
ml-dash upload -t alice/shared-project          # into another project
ml-dash upload --tracks robot_position.jsonl --remote-path tom/proj/exp/robot/position

ml-dash download

bash
ml-dash download [PATH] [options]

Downloads experiments into a local storage directory (PATH, default ./.dash) in the same layout local mode writes.

FlagDescription
-p, --project (aliases --prefix, --pref, --proj)Project or glob to download, e.g. alice/my-project, 'tut*'
--experiment NAMEOnly this experiment. Needs --project
--skip-logs, --skip-metrics, --skip-files, --skip-paramsLeave that kind of data out
--dry-runPreview without downloading
--overwriteOverwrite experiments that already exist locally
--resumeResume an interrupted download
--state-file FILEState file for --resume (default .dash-download-state.json)
--batch-size NBatch size for logs and metrics (default 1000, max 10000)
--max-concurrent-metrics NParallel metric downloads (default 5)
--max-concurrent-files NParallel file downloads (default 3)
--tracks PATHDownload one track instead, e.g. namespace/project/exp/robot/position
-f, --formatTrack export format (default jsonl)
-o, --output FILETrack output file (default: named after the topic)
-v, --verboseDetailed progress
bash
ml-dash download -p alice/my-project
ml-dash download ./backup -p alice/my-project --experiment exp-one
ml-dash download -p 'alice/tut*' --dry-run
ml-dash download --tracks alice/proj/exp/robot/position -f jsonl -o joints.jsonl

ml-dash api

bash
ml-dash api (--query QUERY | --mutation MUTATION) [--jq PATH] [--dash-url URL]
FlagDescription
-q, --queryGraphQL query
-m, --mutationGraphQL mutation
--jq PATHPull out one value with a dot path, e.g. .me.username
  • A bare body is wrapped for you: me { username } is sent as { me { username } }.
  • Single quotes are converted to double quotes, so you can write user(title: 'hello') inside a double-quoted shell string.
  • --jq paths start from the response data. There is no top-level data key, so write .me.username, not .data.me.username.
bash
ml-dash api --query "me { username name email }"
ml-dash api --query "me { username }" --jq ".me.username"

ml-dash update

bash
ml-dash update [--check] [--version VERSION] [--json]
FlagDescription
--checkReport whether an update exists. Change nothing
--versionInstall this exact release instead of the latest
--jsonOutput as JSON

Updates through the channel you installed from. An npm install is updated with npm install -g @dreamlake/ml-dash@<version>. A standalone binary downloads the new build, checks its sha256 and size against the release manifest, runs it once, and only then replaces itself. update refuses to downgrade. It also refuses to touch a copy it doesn't own (Homebrew, Nix, pipx, a node_modules tree) and tells you which tool to use instead.

ml-dash version

bash
ml-dash version        # also: ml-dash --version, ml-dash -V

Files and environment variables

Used for
~/.dash/config.jsonremote_url, an optional api_key (used instead of the stored login), auth_url, and the device-flow secret
~/.dash/tokens.encrypted, ~/.dash/encryption.keyThe token, when no keychain is used
ML_DASH_CONFIG_DIRUse a different directory than ~/.dash for the CLI. The Python SDK always reads ~/.dash
ML_DASH_NO_KEYCHAIN=1Never use the OS keychain. Store and read the token in the encrypted file

Troubleshooting

ml-dash: command not found after upgrading the SDK. Since SDK 0.7.0, pip doesn't install the CLI. Install it as shown in Install. python -m ml_dash.cli no longer exists.

Authentication errors. Run ml-dash profile. It reports an expired token. Then run ml-dash logout && ml-dash login.

The SDK can't find your login but the CLI can. The SDK and the CLI must agree on where the token lives. See Using the token from Python.