# CLI Reference

  The complete `dreamlake` command surface. If you're new, start with the
  worked examples in <a href="/#your-first-episode">Your First Episode</a> — this page
  is the reference you come back to.

> **Note:** The canonical, per-command reference lives at
> [cli.dreamlake.ai](https://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.

All commands use the `dreamlake` entry point. Add `--debug` before any command
to target local dev servers instead of production.

## Auth

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

## Files

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

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

## Collections

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

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

# Episodes
dreamlake list episode --project <target>
```

## Search

```bash
dreamlake vectorize --episode <target>                           # CLIP + LLaVA on video chunks
dreamlake vectorize --bindr <name> --project <target>            # Vectorize bindr scope
dreamlake vectorize --dataset <name> --project <target>          # Vectorize dataset scope
```

Add `--zaku-url <url>` for distributed processing. See
[Semantic Search](/search.md) for the pipeline this feeds.

## Artifacts

Renderable documents — HTML, React, Markdown, SVG, Mermaid, or code — rendered
live in the dashboard at `/<namespace>/artifacts`. New here? The
[Artifacts guide](/artifacts.md) 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
dreamlake artifact push <file>                                       # kind auto-detected from extension
dreamlake artifact push <file> --title <t> --kind <k> --id <id>      # --namespace <ns> to target another namespace
dreamlake artifact push <file> --visibility public                   # readable without login (default: private)
dreamlake artifact push <file> --share                               # mint a ?share= link (signed-in users only)
dreamlake artifact list                                              # list a namespace's artifacts (from the catalog)
dreamlake artifact delete <id>                                       # soft delete → Trash (-y to skip the confirm)
dreamlake artifact restore <id>                                      # bring a soft-deleted artifact back
dreamlake 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.

### Add the artifacts skills (Claude)

DreamLake publishes a [Claude](https://claude.ai/code) **skill** that teaches
your agent to publish, version, and share artifacts for you. Add it from the
public [`dreamlake-skills`](https://github.com/dreamlake-ai/dreamlake-skills)
repo:

```bash
git clone https://github.com/dreamlake-ai/dreamlake-skills.git ~/dreamlake-skills
mkdir -p ~/.claude/skills
ln -s ~/dreamlake-skills/dreamlake-artifacts ~/.claude/skills/
ln -s ~/dreamlake-skills/dreamlake-artifact-authoring ~/.claude/skills/
```

Install both skills: one publishes, the other prepares content for the offline
rendering frame. To update both, run `git -C ~/dreamlake-skills pull --ff-only`.
Use a project's `.claude/skills/` directory for project scope. If a skill already
exists, inspect and preserve local edits before replacing it with a symlink.

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

## Envs

Simulation environments — a directory holding one MJCF scene or one URDF
robot plus its assets, viewed as a live, interactive 3D page at
`/<namespace>/envs`. New here? The
[Envs guide](/envs.md) is the picture-book version. Each env 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
dreamlake env push <dir>                              # entry auto-detected (MJCF, else *.urdf); prints an open link
dreamlake env push <dir> --entry scene.mjcf           # pick the entry when several qualify
dreamlake env push <dir> --type isaaclab              # simulator family (auto-detected: mujoco | urdf — both have viewers)
dreamlake env push <dir> --visibility public          # viewer opens without login (default: private)
dreamlake env push <dir> --thumbnail cover.png        # set the gallery cover (PNG ≤ 512 KiB) — see the Envs guide's Thumbnails section
dreamlake env create <dir>                            # push that FAILS if the name already exists
dreamlake env list                                    # a namespace's envs (name, type, files, entry)
dreamlake env pull <name>                             # latest version → ./<name>/, hash-verified
dreamlake env pull <name>@2 -o <dir> --force          # a specific version; --force writes into a non-empty dir
dreamlake env delete <name>                           # soft delete (restorable; -y to skip the confirm)
dreamlake env restore <name>                          # bring it back
dreamlake env delete <name> --permanent               # purge storage + catalog — IRREVERSIBLE
```

Names are `namespace/env-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 envs existed, `dreamlake env` switched login
> environments. That command is now `dreamlake auth env list|use|remove` — see
> [Environments](https://cli.dreamlake.ai/environments/).

## The CLI itself

```bash
dreamlake --version                          # print the version
dreamlake doctor                             # install + auto-update diagnostics
dreamlake self-update                        # update now (background checks are automatic)
dreamlake self-update <version>              # pin to an exact version (pauses auto-update)
dreamlake self-update channel stable         # switch release channel: latest | stable (unpins)
dreamlake self-update --status               # version, channel, pin, last check
dreamlake 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](/index.md#install-reference) for the install layout, release channels,
and the variables that switch auto-update off.

## Legacy

```bash
dreamlake video upload <file> --user <owner> --project <proj>   # Direct BSS upload (bypasses server)
dreamlake video download <id> --output <path>                    # Download by BSS video ID
dreamlake video list --user <owner> --project <proj>             # List BSS videos
```

## Next steps

    The REST endpoints behind every command on this page.

    Work with the uploaded video from Python — slicing, frames, tensors.