---
title: CLI Reference
description: 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:

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

lenso --version
lenso --help
```

## Compose

Materialize an exact product blueprint:

```sh
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:

```sh
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:

```sh
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](https://github.com/LioRael/lenso/issues/540).

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

```sh
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:

```sh
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:

```text
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

```sh
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](/docs/module-authoring) and
[Module Console UI](/docs/console-packages).

## Provider workspace

Create a TypeScript Provider scaffold from a Host checkout:

```sh
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:

```sh
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:

```sh
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](/docs/autonomous-services). 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:

```sh
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:

```sh
pnpm acceptance:support-desk
```

This is the product-level black-box entrypoint. See [Examples](/docs/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.