Lucid Agents Docs

The CLI validates a template and framework adapter, builds the project in a staging directory, writes wizard answers to the generated environment, and optionally installs dependencies. It commits the target only after those steps succeed. It is a project generator, not a runtime dependency.

Usage

This page describes the repository's Next CLI. Build and invoke the local artifact:

bun run build:packages
bun packages/cli/dist/index.js my-service --adapter=hono --template=blank

For a reproducible Next scaffold:

bun packages/cli/dist/index.js my-service \
  --adapter=hono \
  --ui-preset=folio \
  --template=blank \
  --non-interactive \
  --PAYMENTS_NETWORK=eip155:84532 \
  --PAYMENTS_RECEIVABLE_ADDRESS=0xYOUR_ADDRESS \
  --no-install

Then inspect the generated dependency versions before running bun install. Repository templates track Next and are not a promise that the same package set has been published to npm.

Options

Option	Meaning
`-t, --template <id>`	`blank`, `identity`, `trading-data-agent`, or `trading-recommendation-agent`
`-a, --adapter <id>`	`hono`, `express`, `tanstack-ui`, `tanstack-headless`, or `next`
`--ui-preset <id>`	`dossier`, `folio`, or `console` for every UI-capable adapter
`-i, --install`	Run `bun install` after generation
`--no-install`	Leave dependency installation to the caller
`--no-deploy`	Omit Cloudflare preview tooling from a blank Hono scaffold
`--wizard=no` / `--non-interactive`	Use supplied arguments and template defaults
`--network=<network>`	Compatibility shorthand for `PAYMENTS_NETWORK`
`--KEY=value`	Supply a template wizard value
`-h, --help`	Print the installed CLI's authoritative options

Prefer explicit PAYMENTS_NETWORK=<CAIP-2> values in automation. The template wizard also accepts aliases, but canonical identifiers make logs and provider compatibility checks unambiguous.

Secret-marked wizard values are collected without terminal echo or displayed defaults. Every generated adapter ignores .env while retaining .env.example. Invalid arguments, generation errors, and failed --install runs return an error without leaving a partial target directory.

Adapters

Adapter	Generated integration
`hono`	Hono app plus a static, read-only storefront
`express`	Express app plus a static, read-only storefront
`tanstack-ui`	TanStack Start service storefront and route modules
`tanstack-headless`	TanStack Start route modules without the storefront
`next`	Next.js App Router modules; there is no standalone Next.js adapter package

The trading templates currently target Hono and Express. They still contain pre-v3 composition and are not covered by the generated-project verification matrix; use blank or identity until their generated source/dependencies are migrated and tested. Blank and identity support every adapter listed above.

Templates

blank provides the smallest runtime and echo capability.
identity adds wallets, ERC-8004 configuration, payments, and trust metadata.
trading-data-agent documents the target shape for a priced merchant but is currently migration-required.
trading-recommendation-agent documents the target buyer composition but is currently migration-required.

Generated code follows the selected adapter's canonical binding. For example, Hono uses createAgentApp(runtime), while TanStack uses createTanStackRuntime(runtime) and registers capabilities on its runtime.

Every adapter except tanstack-headless writes one typed root service-ui.config.ts. dossier is dark and monospaced, folio is light and editorial, and console is compact and dark. Users may edit the preset plus validated semantic color/font tokens. Every UI-capable adapter renders the same read-only endpoint, payment-method, and price table.

Stable installation path

The current Stable quickstart deliberately pins the public CLI and runtime versions, then installs the direct x402 buyer dependencies needed by its tested transaction. Follow Install Lucid, not a Next template, when reproducibility matters.

bunx @lucid-agents/cli@2.5.0 my-service --adapter=hono --template=blank

The programmatic surface is intentionally small:

export { runCli } from '@lucid-agents/cli';
export type { PromptApi, RunLogger } from '@lucid-agents/cli';