@dreamlake/lakeshore

Compute launch and management CLI for the Lakeshore platform. The lakeshore command registers providers, dispatches smoke tests, and manages worker daemons against a Lakeshore control plane.

Install

npm install -g @dreamlake/lakeshore

Quick start

# Authenticate with the control plane
lakeshore auth login

# Register a cloud provider
lakeshore providers add --name my-aws --type aws

# Install the worker daemon on a remote host
lakeshore daemon install user@host

# List running daemons
lakeshore daemon list

# Submit and inspect jobs
lakeshore jobs list

# Run the native Python queue worker on THIS machine, supervised by the
# CLI (spawns `python -m dreamlake.lakeshore.daemon`; flags you omit
# fall back to the module's LAKESHORE_* env vars)
lakeshore worker start --queue gpu --url https://cp.example.com
lakeshore worker once --queue smoke     # drain one job, then exit

Development

git clone https://github.com/dreamlake-ai/lakeshore.git
cd lakeshore
pnpm install
pnpm build      # compile TypeScript to dist/cli/
pnpm test       # type-check + node --test

During development you can run the CLI directly from source:

pnpm cli -- <subcommand>

Bun

The CLI runs under Bun as well as Node — the bin shim detects the runtime and imports the TypeScript source directly (no tsx loader) when Bun executes it:

bun bin/lakeshore.js <subcommand>   # or: pnpm cli:bun <subcommand>
pnpm test:bun                       # the suite under bun's node:test shim
pnpm test:e2e:worker                # worker round-trip against the Python SDK

Known gap under bun test (upstream, not a CLI bug): Bun's node:test shim cannot run subtests (oven-sh/bun#5090), which fails a handful of files that pass under pnpm test.

The worker e2e (pnpm test:e2e:worker) needs a python interpreter that can import dreamlake.lakeshore; it prints SKIP and exits 0 when none is found. Point LAKESHORE_WORKER_E2E_PYTHON at a venv to opt in.

Source layout

All CLI source lives under src/cli/.

src/cli/
├── index.ts            CLI entry point (Commander wiring)
├── config.ts           Runtime config (control-plane URL, auth token)
├── config-commands.ts  `lakeshore config` subcommands
├── helpers.ts          Shared utilities (HTTP, formatting, retries)
├── resolver.ts         Endpoint and resource resolution
├── project-config.ts   Per-project configuration (lakeshore.yaml)
├── server.ts           Local helper server for auth flows
├── elf.ts              ELF binary helpers for daemon distribution
├── admin/              Admin-only diagnostic commands
├── auth/               Login, logout, credential storage
├── aws/                AWS-specific provider operations
├── gcp/                GCP-specific provider operations
├── code/               Code archive push and management
├── completion/         Shell completion generation
├── compose/            Multi-service compose definitions
├── daemon/             Daemon install, start, stop, logs over SSH
├── docker/             Docker runner management
├── jobs/               Job submission, listing, and inspection
├── kube/               Kubernetes cluster integration
├── modes/              Execution mode configuration
├── mounts/             Storage mount definitions
├── nymph/              Nymph daemon binary management
├── providers/          Provider registration and lifecycle
├── queues/             Queue creation and management
├── run/                Ad-hoc run dispatch
├── scripts/            Shell scripts shipped with the package
├── secrets/            Secret management for jobs
├── slurm/              Slurm cluster integration
├── ssh/                SSH session helpers
├── storages/           Storage backend configuration
├── tunnels/            Tunnel setup for remote access
├── worker/             Native Python queue worker (spawn + supervise)
└── __tests__/          Test suite (node --test)

Architecture notes

• The CLI communicates with the control plane (lakeshore-controlplane) over HTTP. The base URL is configured via lakeshore config or the LAKESHORE_URL environment variable.
• Daemon installation and management commands connect to remote hosts over SSH.
• Built with Commander for argument parsing and @inquirer/prompts for interactive flows.

Documentation

Full documentation is available at https://lakeshore.dreamlake.ai/cli.

License

See LICENSE.