DreamLake

CLI Reference

The complete dl command surface. If you're new, start with the worked examples in Your First Episode — this page is the reference you come back to.

The CLI has its own docs site

The canonical, per-command reference lives at cli.dreamlake.ai — it versions with each CLI release (the version switcher pins any past release), covers the newer command groups (agents, skills, sources, snapshots, lakeshore resources), and documents both install channels: the native installer and npm install @dreamlake/dreamlake-cli. The summary below covers the core commands; for anything not listed here, go there.

Use dl for new commands. The longer dreamlake command remains supported. For installation, automatic setup on existing machines, and command conflicts, see CLI installation. Add --debug before any command to target local dev servers instead of production.

Auth

bash
dl login --url <server>    # OAuth device auth flow (--no-browser for QR code)
dl logout                  # Remove stored credentials
dl profile                 # Show current user

Files

bash
dl upload <file> --episode <target> --to <path>   # Upload file (type auto-detected)
dl upload <dir>  --episode <target> --to <path>   # Upload folder (--yes to skip prompt)
dl download --episode <target> --from <path> -o <out>
dl list --episode <target>                        # List assets (--type video to filter)

Upload flags: --type <override>, --bindr <names> (comma-separated, auto-created). <target> uses the episode syntax [namespace@]project[:episode].

Collections

bash
# Bindrs — curated file collections matched by glob
dl create bindr <name> --project <target>             # --episode <glob> to match episodes
dl update bindr <name> --project <target> --add <glob>
dl delete bindr <name> --project <target>
dl list bindr --project <target>

# Datasets — groups of bindrs
dl create dataset <name> --project <target>
dl update dataset <name> --project <target> --add <glob>
dl delete dataset <name> --project <target>
dl list dataset --project <target>

# Episodes
dl list episode --project <target>

Artifacts

Renderable documents — HTML, React, Markdown, SVG, Mermaid, or code — rendered live in the dashboard at /<namespace>/artifacts. New here? The Artifacts guide is the two-minute picture-book version. Each artifact is its own versioned dataset; the DreamLake server keeps the catalog (title, kind, visibility) that powers the gallery and list.

bash
dl artifact push <file>                                       # kind auto-detected from extension
dl artifact push <file> --title <t> --kind <k> --id <id>      # --namespace <ns> to target another namespace
dl artifact push <file> --visibility public                   # readable without login (default: private)
dl artifact push <file> --share                               # mint a ?share= link (signed-in users only)
dl artifact list                                              # list a namespace's artifacts (from the catalog)
dl artifact delete <id>                                       # soft delete → Trash (-y to skip the confirm)
dl artifact restore <id>                                      # bring a soft-deleted artifact back
dl artifact delete <id> --permanent                           # purge storage + catalog — IRREVERSIBLE

Kinds: html · react (must define an App component) · markdown · svg · mermaid · code. Re-push with the same --id to append a new version — the viewer keeps every version. After a successful push the CLI prints an open link to the artifact, so you can click straight through to view what you just uploaded.

Visibility & sharing. Artifacts are private by default (visible only to namespace members). --visibility public makes one readable by anyone; --share mints a ?share=<token> link that any signed-in DreamLake user can open (anonymous visitors are sent to log in first). Members can also toggle visibility and copy a share link from the artifact's page in the dashboard.

Delete, Trash & restore. delete is a soft delete: the artifact moves to your gallery's trash tab (share links stop working immediately), and you can bring it back with restore, the Restore button in the Trash, or simply by re-pushing the same --id. delete --permanent (v0.4.14+) permanently erases the artifact — every version, its stored content, and its catalog entry. There is no undo; the dashboard's equivalent is Delete forever in the Trash. With a server that includes the issue #1343 fix (not yet released), both remove the artifact from every project it was filed in, and a restore does not re-file it.

Add the artifacts skill (Claude)

DreamLake publishes a Claude skill that teaches your agent to prepare, publish, version, and share artifacts for you. It is written in the public dreamlake-skills repo and installed by the CLI:

bash
dl init                              # once: pick your agent and scope
dl skill install dreamlake-artifacts

dl skill update brings in new releases without touching files you have edited. Without the CLI, download skills.tar.gz from the latest dreamlake-skills release and copy dreamlake-artifacts/ and dreamlake-cli/ into ~/.claude/skills/ (or a project's .claude/skills/).

Then ask Claude something like "push this dashboard as a dl artifact and make it public" — it will invoke the skill and run the right dl artifact commands.

Scenes

Versioned scenes — a directory holding one MJCF scene or one URDF robot plus its assets, viewed as a live, interactive 3D page at /<namespace>/scenes. New here? The Scenes guide is the picture-book version. Each scene stores its files content-addressed, so re-pushing uploads only what changed, and pull returns a byte-identical directory (every file is hash-verified).

bash
dl scene push <dir>                              # entry auto-detected (MJCF, else *.urdf); prints an open link
dl scene push <dir> --entry scene.mjcf           # pick the entry when several qualify
dl scene push <dir> --type isaaclab              # simulator family (auto-detected: mujoco | urdf — both have viewers)
dl scene push <dir> --visibility public          # viewer opens without login (default: private)
dl scene push <dir> --thumbnail cover.png        # set the gallery cover (PNG ≤ 512 KiB) — see the Scenes guide's Thumbnails section
dl scene create <dir>                            # push that FAILS if the name already exists
dl scene list                                    # a namespace's scenes (name, type, files, entry)
dl scene pull <name>                             # latest version → ./<name>/, hash-verified
dl scene pull <name>@2 -o <dir> --force          # a specific version; --force writes into a non-empty dir
dl scene delete <name>                           # soft delete (restorable; -y to skip the confirm)
dl scene restore <name>                          # bring it back
dl scene delete <name> --permanent               # purge storage + catalog — IRREVERSIBLE

Names are namespace/scene-name with immutable integer versions — re-push the same name to append the next version, and the viewer keeps a version picker. Limits per version: ≤ 1000 files, ≤ 100 MiB per file, ≤ 1 GiB total; dot-files, node_modules and symlinks are skipped.

Renamed: before scenes existed, dl env switched login environments. That command is now dl auth env list|use|remove — see Environments.

The CLI itself

bash
dl --version                          # print the version
dl doctor                             # install + auto-update diagnostics
dl self-update                        # update now (background checks are automatic)
dl self-update <version>              # pin to an exact version (pauses auto-update)
dl self-update channel stable         # switch release channel: latest | stable (unpins)
dl self-update --status               # version, channel, pin, last check
dl install [latest|stable|<version>]  # re-install the native binary

Note the name: update edits bindrs and datasets, self-update updates the CLI. See the install reference for the install layout, release channels, and the variables that switch auto-update off.

Next steps

API Reference →

The REST endpoints behind every command on this page.