dreamlake-cli

dreamlake — a data-warehouse CLI for DreamLake. Uploads/downloads assets and manages episodes, bindrs, and datasets against a DreamLake server + BSS (big-streaming-server).

It is a TypeScript port of the CLI shipped in dreamlake-py (dreamlake.cli), built on the lakeshore conventions (Commander + native fetch, pure ESM, token saved to a flat YAML file instead of the system keyring).

The compiled dreamlake binary shares its name with the Python dreamlake entry point — this CLI is the TypeScript replacement. When both are on a machine, PATH order decides which one runs.

Install / run

pnpm install
pnpm cli --help          # dev — runs the TS source through tsx
pnpm build               # emit dist/
node bin/dreamlake.js …  # prod — runs compiled dist/ (falls back to tsx in dev)

Auth & environments

The CLI knows two built-in environments — staging and prod — so you never type their URLs. Each environment keeps its own token; switch between them with one command.

dreamlake login --env staging       # device-authorization flow (opens browser)
dreamlake login --env prod          # built-in URLs; no --url/--bss needed
dreamlake login                     # re-auth the active env (or staging if none)

dreamlake env list                  # show logged-in envs (* = active)
dreamlake env use prod              # switch active env — no URLs, no re-login
dreamlake env remove staging        # forget a saved env

dreamlake profile                   # current user (shows [env: ...])
dreamlake logout                    # log out of the active env only

Custom / self-hosted environments — define once, then switch by name forever:

dreamlake login --env dev --url https://dev-api.example.com --bss https://dev-bss.example.com
dreamlake env use dev

Flags / env vars (DREAMLAKE_REMOTE, DREAMLAKE_BSS_URL, DREAMLAKE_API_KEY) still override the active environment for one-off commands. --token <jwt> saves a token directly (skip the device flow). --auth <url> overrides the vuer-auth server (built-ins set this automatically; staging needs staging-auth.vuer.ai).

Credentials live in ~/.config/dreamlake/auth.yml ($XDG_CONFIG_HOME/dreamlake/auth.yml, chmod 600) as a multi-environment file:

current: prod
envs:
  staging: { server, bss, auth, namespace, token }
  prod:    { server, bss, auth, namespace, token }

Targets

Most commands take a target string:

--episode  space[@namespace][:episode]      # e.g. robotics@alice:2026/q1/run-042
--project  space[@namespace]                 # e.g. robotics@alice

When @namespace is omitted it is resolved from your token (/auth/me).

Commands

# Upload — single file, or a flat directory (resumable). Type auto-detected.
dreamlake upload ./mic.wav   --episode robotics@alice:run-042 --to /microphone/front
dreamlake upload ./clip.mp4  --episode robotics:run-042       --to /camera/front --bindr cam-set
dreamlake upload ./capture/  --episode robotics@alice:run-042 --to /sensors --yes

# Download — a single file, or a whole folder/episode recursively.
dreamlake download --episode robotics@alice:run-042 --from /camera/front/clip.mp4 -o ./clip.mp4
dreamlake download --episode robotics@alice:run-042 --from /camera -o ./out/

# Projects. Private by default — pass --public (or --visibility public) to share.
dreamlake create project my-robots --description "robot captures"   # private
dreamlake create project shared-set --public                        # public
dreamlake update project my-robots --public                         # flip visibility later
dreamlake list project
dreamlake delete project my-robots            # HARD-deletes the whole subtree

# List — assets (default), or projects / bindrs / datasets / episodes.
dreamlake list --episode robotics@alice:run-042 --type video
dreamlake list project
dreamlake list bindr   --project robotics@alice
dreamlake list dataset --project robotics@alice --json
dreamlake list episode --project robotics@alice

# Delete uploaded data (all HARD deletes — confirm prompt unless --yes).
dreamlake delete file /camera/front/clip.mp4 --episode robotics@alice:run-042
dreamlake delete episode run-042 --project robotics@alice

# Bindrs (members are episodes, matched by node-path glob).
dreamlake create bindr front-cam --project robotics@alice --episode "camera/front/*"
dreamlake update bindr front-cam --project robotics@alice --add "2026/04/*"
dreamlake delete bindr front-cam --project robotics@alice

# Datasets (members are bindrs, matched by name glob).
dreamlake create dataset train-v1 --project robotics@alice --tags robotics,training
dreamlake update dataset train-v1 --project robotics@alice --add "front-*"
dreamlake delete dataset train-v1 --project robotics@alice

Videos are just files — upload/list/download them with upload / list --type video / download, no dedicated video command needed.

# Organizations (GraphQL-backed; same token). Members resolve by email/name.
dreamlake org list
dreamlake org show my-org
dreamlake org create my-org --name "My Org" --description "..."   # you become OWNER + a namespace is created
dreamlake org update my-org --description "..."
dreamlake org delete my-org                                       # must have no remaining projects
dreamlake org leave my-org
dreamlake org member list   my-org
dreamlake org member add    my-org [email protected] --role member
dreamlake org member role   my-org [email protected] --role owner
dreamlake org member remove my-org [email protected]

# Teams (scoped to an org; nestable via --parent; visible|secret).
dreamlake team list                                  # all teams you belong to
dreamlake team list my-org                            # teams in one org
dreamlake team show   my-org backend
dreamlake team create my-org backend --name "Backend" --visibility secret
dreamlake team create my-org api --parent backend    # nested team
dreamlake team update my-org backend --visibility visible
dreamlake team delete my-org backend                 # must have no child teams
dreamlake team leave  my-org backend
dreamlake team member list   my-org backend
dreamlake team member add    my-org backend [email protected] --role maintainer
dreamlake team member role   my-org backend [email protected] --role member
dreamlake team member remove my-org backend [email protected]

Configuration

Resolution precedence (high → low): flag → env var → saved auth.yml → default.

| Setting | Env var | Default | | --- | --- | --- | | DreamLake server | DREAMLAKE_REMOTE | http://localhost:10334 | | BSS server | DREAMLAKE_BSS_URL | http://localhost:10234 | | Token | DREAMLAKE_API_KEY | (from auth.yml) |

Not implemented

By design, the CLI excludes the parts of dreamlake-py that aren't command-line-shaped: vectorize (CLIP/LLaVA inference + Zaku + Qdrant), the SDK-only rich types (Video/TextTrack/VectorIndex), and the deprecated Episode-tracking stack.

Development

pnpm test     # tsc --noEmit + node --test (target/glob/kinds/credentials)
pnpm build    # tsc → dist/