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).
| Command | Description |
|---|---|
login | Authenticate with the OAuth device flow |
logout | Clear the stored token |
profile | Show the current user and configuration |
list | List projects, experiments, and tracks on the server |
create | Create a project |
remove | Delete a project and everything in it |
upload | Upload locally stored experiments to the server |
download | Download experiments from the server to local storage |
api | Send a raw GraphQL query or mutation |
update | Update the CLI itself |
version | Print 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 group | Accepted actions |
|---|---|
auth | status, login |
instance | show, capabilities |
orgs | list, create, update, delete, members, teams, member-add, member-role, member-remove |
projects | list, access |
teams | list, members (standalone diagnostics) |
setup | plan, apply, status, resume |
credentials | list, inspect, create, rotate, retire |
runs | list, show, create, status, parameters, delete |
metrics | list, read, append |
logs | read, append |
files | list, inspect, upload, download |
health, diagnostics | check |
connections | list |
workspaces | list, status, plan, apply, detach |
adoption | inventory, 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
| Options | Purpose |
|---|---|
--namespace, --project | Explicit DreamLake organization and project selection |
--dreamlake-url | BFF matching the existing shared DreamLake login |
--standalone, --dash-url, --api-url | Explicit separate Dash authority and server |
--run, --run-key, --metric, --file | Stable resource IDs, run creation key or exact metric name |
--name, --description, --user, --role OWNER/MEMBER | Reviewed organization metadata or explicit membership target |
--limit, --cursor | Bounded pages and opaque continuation cursor |
--offset, --team | Standalone list continuation and team diagnostics |
--data FILE, --input FILE, --content-type | JSON workload input or file attachment; --data - reads stdin |
--status, --mode read/write | Run status or session mode; status accepts RUNNING/COMPLETED/FAILED/CANCELLED |
--credential, --expected-generation | Scoped writer metadata and reviewed generation |
--out, --review, --apply, --idempotency-key | Non-secret exact review/receipt, explicit apply and stable intent |
--connection, --remote-namespace | Operator-approved external alias and verified namespace |
--remote-project, --expected-revision, --plan-hash | Explicit legacy adoption target and authority review |
--json, --no-browser, --auth-url | Structured 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.
--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.
Machine-readable inspection (0.3.0)
CLI 0.3.0 exposes these local and server inspection commands:
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
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.
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.
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.
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:
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
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.
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.
| Surface | Actual API |
|---|---|
| Login/status | Vuer device start/poll; DreamLake /auth/exchange, /auth/me |
| Instance/discovery | BFF /managed-experiments/capabilities, /namespaces, /ns/:ns/projects |
| Organization membership | Fixed typed DreamLake GraphQL operations; no user-supplied query |
| Setup/status | BFF project /setup, /status with durable CAS/intent receipt |
| Credentials | BFF project /credentials, /credentials/:id; scoped /session only in memory |
| Reads | BFF project /runs, metrics/logs/files and verified file download |
| Writes | Dash /api/managed/projects/:stableId/runs/... with short scoped session |
| External workspaces | BFF /integrations/dash/ns/:ns/connections, /workspaces, /binding |
| Adoption | BFF project /adoption/:legacyProjectId/{inventory,plan,apply,reconcile,recover} |
Standalone common options
| Flag | Description |
|---|---|
--dash-url, --api-url URL | Server 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, --help | Show help for the command |
ml-dash login
| Flag | Description |
|---|---|
--dash-url, --api-url | ML-Dash server to log in to |
--auth-url | OAuth authorization server (default https://auth.vuer.ai) |
--no-browser | Print 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
Clears the stored token from the keychain and from the ~/.dash/ token files.
ml-dash profile
| Flag | Description |
|---|---|
--json | Output as JSON |
--cached | Read 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
| Flag | Description |
|---|---|
-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, --namespace | Namespace for all queries. Defaults to your own |
--status | Filter experiments: COMPLETED, RUNNING, FAILED, or ARCHIVED |
--tags | Filter experiments by tags (comma-separated) |
--detailed | Show more columns |
--tracks | List the tracks in one experiment. Needs -p namespace/project/experiment |
--topic-filter | Filter tracks by topic, e.g. 'robot/*' |
-v, --verbose | Verbose 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:
| Input | Searches |
|---|---|
tes* | <your-namespace>/tes*/* |
tom/tes* | tom/tes*/* |
tom/test/exp* | tom/test/exp* |
ml-dash create
| Flag | Description |
|---|---|
-p, --project | project or namespace/project. Without a namespace, your own is used |
-d, --description | Optional description |
If the project already exists, create prints a warning and exits
successfully.
ml-dash remove
| Flag | Description |
|---|---|
-p, --project | project or namespace/project |
-y, --yes | Skip the confirmation prompt |
remove deletes the project and all of its experiments, metrics, files, and
logs. It cannot be undone.
ml-dash upload
Uploads experiments that the SDK wrote in local mode. PATH is the local
storage directory and defaults to ./.dash.
| Flag | Description |
|---|---|
-p, --project (aliases --prefix, --pref, --proj) | Only upload experiments matching this prefix or glob, e.g. 'tom/*/exp*' |
-t, --target | Upload under this prefix on the server instead, e.g. alice/shared-project |
--skip-logs, --skip-metrics, --skip-files, --skip-params | Leave that kind of data out |
--dry-run | Show what would be uploaded without uploading |
--strict | Fail on any validation error. By default, invalid data is skipped |
--batch-size N | Batch size for logs and metrics (default 100) |
--resume | Resume an interrupted upload |
--state-file FILE | State file for --resume (default .dash-upload-state.json) |
--tracks FILE | Upload a single track data file (e.g. robot_position.jsonl). Needs --remote-path |
--remote-path PATH | Where the track goes, e.g. namespace/project/exp/robot/position |
-v, --verbose | Show detailed progress |
ml-dash download
Downloads experiments into a local storage directory (PATH, default
./.dash) in the same layout local mode writes.
| Flag | Description |
|---|---|
-p, --project (aliases --prefix, --pref, --proj) | Project or glob to download, e.g. alice/my-project, 'tut*' |
--experiment NAME | Only this experiment. Needs --project |
--skip-logs, --skip-metrics, --skip-files, --skip-params | Leave that kind of data out |
--dry-run | Preview without downloading |
--overwrite | Overwrite experiments that already exist locally |
--resume | Resume an interrupted download |
--state-file FILE | State file for --resume (default .dash-download-state.json) |
--batch-size N | Batch size for logs and metrics (default 1000, max 10000) |
--max-concurrent-metrics N | Parallel metric downloads (default 5) |
--max-concurrent-files N | Parallel file downloads (default 3) |
--tracks PATH | Download one track instead, e.g. namespace/project/exp/robot/position |
-f, --format | Track export format (default jsonl) |
-o, --output FILE | Track output file (default: named after the topic) |
-v, --verbose | Detailed progress |
ml-dash api
| Flag | Description |
|---|---|
-q, --query | GraphQL query |
-m, --mutation | GraphQL mutation |
--jq PATH | Pull 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. --jqpaths start from the response data. There is no top-leveldatakey, so write.me.username, not.data.me.username.
ml-dash update
| Flag | Description |
|---|---|
--check | Report whether an update exists. Change nothing |
--version | Install this exact release instead of the latest |
--json | Output 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
Files and environment variables
| Used for | |
|---|---|
~/.dash/config.json | remote_url, an optional api_key (used instead of the stored login), auth_url, and the device-flow secret |
~/.dash/tokens.encrypted, ~/.dash/encryption.key | The token, when no keychain is used |
ML_DASH_CONFIG_DIR | Use a different directory than ~/.dash for the CLI. The Python SDK always reads ~/.dash |
ML_DASH_NO_KEYCHAIN=1 | Never 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.