# lenso-cli
Command-line interface for the Lenso backend framework.
## Install
```sh
cargo install lenso-cli
```
## Scaffold a host application
```sh
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:
```sh
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`](https://github.com/LioRael/lenso/blob/main/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
```sh
lenso module create billing
```
Add `--with-console` when the linked module should also get a Runtime Console
workspace package:
```sh
lenso module create billing --with-console
```
For a standalone remote package:
```sh
lenso module create billing --remote --output-dir ../module-packages
```
The Runtime Console package generator is available directly as:
```sh
lenso console-package create billing
```
## Install a module
```sh
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:
```sh
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:
```sh
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:
```sh
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.
```sh
lenso module install auth --source linked
lenso module uninstall auth --source linked
```