CLI Reference

Current public commands for composing a Lenso app, starting its connected local environment, and reading status.

The lenso CLI owns application composition, local System realization, Module and Service scaffolding, and independent Console installation. The public app lifecycle is Compose → Run locally → Connect → Status.

Install

Install either package that exposes the lenso command:

cargo install lenso-cli
# or
npm install -g @lenso/cli

lenso --version
lenso --help

Compose

Materialize an exact product blueprint:

lenso app compose ./support-desk --blueprint support-desk --apply

--apply is the atomic write flag for the generated lenso.app.json; it is not a separate application-management phase. The bare Support Desk blueprint selects auth, notification-worker, and support-api.

Blueprint browsing commands retained for compatibility are hidden from public help. Use the explicit --blueprint input with lenso app compose in current automation and documentation.

The product acceptance uses a checked-in capability pack. Run this exact command from the lenso-examples repository root:

lenso app compose ./support-desk \
  --blueprint support-desk \
  --pack ./fixtures/acceptance/support-desk/capability \
  --implementation support-api=linked \
  --implementation notification-worker=linked \
  --implementation lenso/platform-story=linked \
  --apply

The pack contributes support/tickets Service delivery and lenso/platform-story. The implementation flags make the local bindings explicit. Because support/tickets is service-backed, the acceptance runner then uses lenso service workspace init --force and lenso service workspace add support-ticket with the Provider’s lenso.service.json. Do not start this pack-backed composition without that workspace entry; use pnpm acceptance:support-desk for the supported complete path.

Run locally

Start the generated Host, auto-start Provider Services, and a connected local Console from the composed Host directory:

cd ./support-desk
lenso dev up --console-root ../lenso-console

The first run securely prompts for the local Operator password. Automation can use --operator-password-file with a private regular file. The command starts and migrates the Host and Console Stores, builds Console, configures or reuses the durable Operator, reconciles Module-owned artifacts, connects the exact topology, and waits in the foreground. Ctrl-C stops only processes started by that invocation.

This is a shipped command for an already composed Host and existing Console checkout. The broader from-empty-directory browser acceptance remains tracked by Lenso issue #540.

Use lenso system dev only when you specifically need the lower-level System Sandbox and its Local Control Adapter:

lenso system dev --system-file ./support-desk/lenso.app.json --dry-run --json
lenso system dev --system-file ./support-desk/lenso.app.json
lenso system dev --system-file ./support-desk/lenso.app.json --cleanup

The sandbox does not start the composed Host or Console and does not connect Console. In App Composition mode it does start the selected service-backed Provider workloads, alongside the Local Control Adapter, inside the bounded sandbox run.

Connect

lenso dev up --console-root creates the loopback-only signed enrollment receipts and .lenso/console-connect.json, then applies the bundle before it reports the local System ready.

For a separately prepared local bundle, the public idempotent connection entrypoint is:

LENSO_CONSOLE_TOKEN='<operator-session-token>' \
  lenso console connect \
  --console-url http://127.0.0.1:3030 \
  --bundle .lenso/console-connect.json

Use --token-file with a private regular file for non-interactive operation. The lenso.console-connect.v1 bundle contains signed enrollment receipts, an optional exact Console Composition artifact effect, and the digest-bound System Connection request. The local enrollment path accepts loopback HTTP targets only. The CLI-owned Local Control Adapter does not use business enrollment; every other topology Service requires an active signed enrollment.

Status

Read the connected System through Console or:

GET /api/console/v1/system
permission: console.system.read

System, Service, Module, Surface, and Adapter projections report connected, unavailable, incompatible, or unmanaged with a direct reason. Workload operational state is separate and reports values such as running, suspended, or unknown. An unavailable Adapter produces unknown Workload observation and rejects mutation without queueing.

Module authoring

lenso module create billing --with-console-ui --dry-run
lenso module create billing --with-console-ui
lenso module dev --console-ui

The scaffold accepts an unqualified local slug such as billing. A product Module keeps its fully qualified business identity—support/tickets in the Support Desk acceptance—whether linked into a Host or delivered by a Service. Console UI is a receipt-bound console_ui_esm artifact in that Module Release. Business operations remain typed Business API operations, not a generic administration channel.

See Module Authoring and Module Console UI.

Provider workspace

Create a TypeScript Provider scaffold from a Host checkout:

lenso service create billing-provider --lang ts --output-dir services --dry-run
lenso service create billing-provider --lang ts --output-dir services
lenso service workspace check --workspace-file lenso.workspace.json --json

Unless --no-workspace is supplied, creation also registers the generated Service in lenso.workspace.json. The generated TypeScript project exposes the current exact Provider runtime:

cd services/billing-provider
pnpm install
pnpm check
pnpm module:release > lenso.module-release.json
pnpm start

In another terminal, install that exact Module Release into the Host runtime inputs using the Provider endpoint:

lenso module install \
  ./services/billing-provider/lenso.module-release.json \
  --base-url http://127.0.0.1:4100/lenso/provider/v1 \
  --repo-root .

The three contracts have different responsibilities:

lenso.service.v1 is compatibility metadata for Service packaging, local process startup, and older discovery consumers.
lenso.module-release.v1 is the exact Module install target and binds its Manifest, delivery, contract, and optional Console artifact digests.
lenso.provider.v1 at /lenso/provider/v1 is the locked descriptor and Host-to-Provider invocation, recovery, and acknowledgement boundary.

The Host verifies the Service Release, Module Release, Manifest, export, and contract digests before activating a Provider export. Provider runtime remains Host-owned and supports Rust and TypeScript. Autonomous Services use Rust lenso.service.v2, own their runtime and storage, and are described in Service Capability Tiers. TypeScript does not provide Autonomous Service parity.

Console operator bootstrap

An installed Console has no default credentials. Bootstrap the first Operator from the external installation authority:

lenso console operator bootstrap \
  --console-root ../lenso-console \
  --console-url http://127.0.0.1:3030 \
  --identifier admin@example.com

Interactive terminals prompt without echoing the password. Automation must use --password-stdin or a private regular file through --password-file.

Product acceptance

From the prepared lenso-examples checkout:

pnpm acceptance:support-desk

This is the product-level black-box entrypoint. See Examples for sibling checkout, PostgreSQL, and browser prerequisites.

Ownership boundary

lenso.app.json is the exact application composition and lock.
lenso dev up owns only its connected local-development processes and connection records; Ctrl-C stops only processes that invocation started.
lenso system dev owns only its lower-level sandbox run and Local Control Adapter.
Console connects and reports the exact topology; it does not create or reconcile production objects.
Production delivery remains repository-, platform-, and operator-owned.