lenso-cli

Command-line interface for the Lenso backend framework.

Install

cargo install lenso-cli

Scaffold a host application

lenso host init my-app
cd my-app
cp .env.example .env
lenso serve

The package name defaults to the target directory name and can be overridden with --name. Pass --force to scaffold into a non-empty directory. Release builds of lenso-cli also copy the bundled Runtime Console into the new project, so the API serves it at /console without requiring Node.js or pnpm in the host application.

Update the hosted console later by upgrading lenso-cli and running:

lenso host update-console

The generated host depends on the Git-pinned lenso crate with the host feature, which is the current narrow host API for booting API, worker, and migration entrypoints. See docs/architecture/framework-public-surface.md for the host-facade roadmap.

lenso serve is a local development wrapper for the generated host. It starts the template Postgres service, runs migrations, then keeps the API and worker running until Ctrl-C. New hosts run them in one local process; pass --separate-worker when you want two child processes. Use --skip-db or --skip-migrate when you already have those steps covered.

Scaffold a module

lenso module create billing

Add --with-console when the linked module should also get a Runtime Console workspace package:

lenso module create billing --with-console

For a standalone remote package:

lenso module create billing --remote --output-dir ../module-packages

The Runtime Console package generator is available directly as:

lenso console-package create billing

Install a module

lenso module install https://example.com/lenso/module/v1/manifest
lenso module install ./lenso.module.json
lenso module install auth

module install reads source from the module descriptor when one is present. Remote modules update REMOTE_MODULES, copy declared Runtime Console bundles to .lenso/console/extensions, update .lenso/console/extensions/registry.json, and record .lenso/module-installs.json in one step. Linked modules update the host Cargo.toml, src/lib.rs, .env toggle, and the same install receipt from the descriptor's linked section. module add remains a compatibility alias for remote installs.

Use --no-console-extension when you want to skip Runtime Console extension registration.

Remote manifests may also declare install.env values and install.commands. Env values are written to .env; commands are run only when you pass:

lenso module install https://example.com/lenso/module/v1/manifest --run-install-commands

For long-running remote module backends, declare install.services. These are stored in .lenso/module-services.json and started before the host loads remote modules on API/worker startup. Services started by the host are tracked with .lock/.pid files and stopped when the owning API/worker process exits; services that are already ready before startup are treated as external and are not stopped by the host.

Diagnose installed remote-module service state with:

lenso module doctor
lenso module doctor billing

The doctor reads REMOTE_MODULES and .lenso/module-services.json, checks service readyUrl endpoints, and points to stale .lock/.pid files when a host-started service did not become ready.

Remove the local remote-module source, install receipt, service state, Runtime Console extension registry entry, and copied bundle files with:

lenso module uninstall billing

Use --source linked only when you need to force the loading source. Prefer descriptors with a source field for new installs.

lenso module install auth --source linked
lenso module uninstall auth --source linked