lecodes-cli

Clone, edit and push LeCodes projects from your machine, with full TypeScript IntelliSense for the platform API in your editor.

The package is lecodes-cli; the command it installs is lecodes.

Install

npm i -g lecodes-cli      # then run: lecodes <command>
# or without installing:
npx lecodes-cli <command>

The render command additionally needs the optional peer lecodes-renderer (>= 0.2.0, for UI + 2D rendering), plus @napi-rs/canvas for PNG output:

npm i -D lecodes-renderer @napi-rs/canvas

Standalone build (the release archive, no Node/Bun needed): unpack it and run ./lecodes install to copy the bundle to a library folder and put lecodes on your PATH — per-user by default, or --system for all users on Linux/macOS. (This archive ships the lecodes binary alongside the chisel bundler and a runtime/ folder; keep them together, or let install place them for you.)

Quick start

Start a project locally — no account, no login:

lecodes init myapp                  # scaffold a local project (starter + types + tsconfig)
cd myapp
#   …edit main.ts in VS Code (IntelliSense works out of the box)…
lecodes dev                         # run it on a device with hot reload (scan the QR)
lecodes preview -o app.js           # compile to a self-contained bundle for LeCodes Desktop

Or work against a project on the platform:

lecodes login                       # opens the browser to authorize this machine
lecodes clone <project-uuid> myapp  # download files + types into ./myapp
cd myapp
#   …edit files in VS Code…
lecodes status                      # see what changed
lecodes push -m "Tweak the menu"    # push as a new checkpoint

Commands

| Command | What it does | | --- | --- | | init [dir] | Scaffold a new local project (no login, no server): a starter main.ts, the SDK types + a tsconfig.json for IntelliSense, and a .lecodesignore. Run it with dev, or compile it with preview. dir defaults to the current folder. Idempotent — existing files are kept. | | install | Standalone build only. Install the unpacked release bundle so lecodes is on your PATH: copies the lecodes+chisel+runtime/ bundle to a library folder, then (Linux/macOS) symlinks it into a bin dir. PATH itself is edited only with --modify-path (appends export PATH=… to your shell rc on Linux/macOS, or adds the folder to your user PATH on Windows); otherwise it prints how to finish. Per-user by default; --system installs to /usr/local (needs sudo, and /usr/local/bin is already on PATH). --dir <path> overrides the library folder, --bin <path> the symlink folder. Refuses when run from an npm/source install (there, install globally with your package manager). | | login | Authorize in the browser; stores an access token in ~/.lecodes/config.json. --token <pat> to use a token created in the web UI instead, --api <url> for the API origin (default https://le.codes), --web <url> for the app origin. | | clone <uuid\|url> [dir] | Download a project's file tree + binary resources, plus .d.ts types and a tsconfig.json for IntelliSense. --no-types to skip types. | | status | Show added / modified / moved / deleted files vs the last sync. | | pull | Overwrite local files with the project's current remote state. --force to discard local edits. | | push | Push all local changes as one new checkpoint. -m/--message for the message, --force to override the "server moved on" guard. | | dev | Run the project on a device straight from your machine, with hot reload — no login or server needed. Starts a LAN dev server and prints a QR code; scan it with the LeCodes app (or pass the URL to the desktop host with ?t=poll). Every save recompiles and hot-swaps the running app in place (errors roll back to the last good version); the device's console.log and errors stream back to the terminal. Assets are served from the working tree; custom shaders still need a prior push (their artifacts compile server-side). --port <n> (default 4499), --host <ip> to override the auto-detected LAN address, --entry <path>, --no-qr. The URL stays stable across runs (token in .lecodes/dev.json). | | preview | Compile the project to a single JS bundle, printed to stdout (pipeable). Works on a cloned/created project (binary asset URLs resolved from the server) or a local init project (no login — asset() resources resolve on the host via fetchLocal, so the bundle is self-contained for LeCodes Desktop). -o/--out <file> to write a file, --entry <path> to override the entrypoint, --no-header to omit the metadata header, --public-url <url> to resolve assets from a URL prefix instead. Diagnostics go to stderr. | | design [serve] | LeCodes Design — a live canvas of screens for AI-driven prototyping (needs the optional lecodes-design package). Works inside a cloned project or standalone in any folder (no login/project needed). Starts a dev server + browser board showing every design/screens/*.ts as a working prototype with the meta.json flow edges; screens hot-reload as files change. Drag an unselected screen anywhere to move it, click to select it — a selected screen is interactive (tap, scroll, type; arrow keys nudge it). The canvas edits meta.json directly: drag the connect handle onto another screen to draw an edge, click an edge to edit its label/activator (with a dropdown of the source screen's named elements) or delete it, click the header note to edit a description. Double-click any rendered text to edit it in place — the string literal is rewritten in the screen's source file (dynamic text is declined safely). Double-click an image (or drop an image file from your OS onto it) to replace it: the file is stored in design/assets/ and the asset() path is rewritten. Hint mode (H) outlines interactive elements, editable texts and replaceable images; selecting or hovering an edge highlights its activator element on the source screen — and hovering that element highlights the edge. Middle-drag or scroll pans from anywhere; ctrl+wheel/pinch zooms. --port <n> (default 4477), --dir <folder> (default design/), --no-open. | | design init | Scaffold the design folder: screens/, shared/, meta.json, and a CLAUDE.md documenting the conventions for AI assistants. | | design snapshot [screen…] | Render design screens headless (needs lecodes-renderer). One screen → semantic JSON to stdout; otherwise JSON files in design/.snapshots/; --png also rasterizes PNGs (needs @napi-rs/canvas); --out-dir <dir>, --logs. | | scene [path] | LeCodes Scene Editor — visually edit a .scene.ts 3D scene (needs the optional lecodes-3d-editor package). Works inside a cloned project or standalone in any folder. Starts a local editor server + browser app: a scene tree, a per-node inspector, and a move/rotate/scale gizmo; add mesh/light/camera/model/aspect nodes; edits are written straight back to the .scene.ts, and external (IDE) edits hot-reload over SSE. Registers an MCP server in .mcp.json so Claude Code can call scene_state (scenes + models + aspect classes with field hints) and check_scene (compile status) — --no-mcp to skip. path is a folder or a .scene.ts to host (default: the current folder / enclosing project). --port <n> (default 4488), --no-open. | | render | Render the local project (UI + 2D). By default emits a semantic JSON description (great for AI/automated checks) to stdout or -o/--out <file>; --png [file] rasterizes a PNG (default screenshot.png, --scale <n> for DPR). A creator-2d scene is composited under the UI; --time <ms> advances its physics/animation. asset('./x.png') resources (images, sprite textures) load from the local working tree by default — use --remote-assets (or an explicit --public-url) to fetch them from the server instead (which then needs --wait-network). --width/--height set the viewport (default 390×844). Requires the optional lecodes-renderer package (npm i -D lecodes-renderer@^0.2.0); PNG also needs @napi-rs/canvas. 3D scenes aren't rendered. |

How it works

• Project metadata and the path → asset map live in .lecodes/ (commit it or not — it's like .git).
• A push sends your whole working tree to the server, which atomically rebuilds the project's file tree (adds, edits, deletes, renames and moves all at once) and freezes a single checkpoint. Renames/moves keep their history; unchanged binaries are never re-uploaded.
• Types are fetched from the server on clone/pull, so they always match the deployed runtime.

Config can also be supplied via the LECODES_API and LECODES_TOKEN environment variables (useful in CI).