lenso-cli
Command-line interface for the Lenso backend framework.
Install
# or
Scaffold a host application
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:
After creating a password user, grant the first Runtime Console admin:
# or
console.admin is always added. Pass extra --scope <name> flags when the
user should also see scoped module data, then restart the API/worker.
The generated host depends on the crates.io 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
Add --with-console when the linked module should also get a Runtime Console
workspace package:
For a standalone remote package:
The Runtime Console package generator is available directly as:
Install a module
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.
Install descriptor profiles let a module expose optional setup without baking module-specific choices into the CLI. For Redis-backed auth sessions:
The auth descriptor applies that profile by enabling the
lenso-module-auth dependency's redis Cargo feature, writing
REDIS_URL=redis://localhost:6379/0 to .env, and recording
auth.session_cache=redis in .lenso/runtime-config-defaults.json. Provide a
Redis service separately; the starter Docker Compose file only starts Postgres
by default.
Reapply an installed module from .lenso/module-installs.json with:
module update reuses the recorded manifestReference and source. Remote
updates refresh REMOTE_MODULES, service state, install receipts, and copied
Runtime Console bundles. Linked updates reapply the recorded descriptor or
builtin module entry.
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:
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:
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:
Use --source linked only when you need to force the loading source. Prefer
descriptors with a source field for new installs.