@lucid-agents/cli

Scaffold a Lucid service for Hono, Express, TanStack Start, or Next.js. The CLI copies a template, applies one adapter, writes wizard values to the generated environment files, and optionally installs dependencies. It is a project generator, not a runtime dependency.

Choose a release channel

The public npm package set is Stable. This repository can be ahead of npm, so pin one channel and inspect the generated dependency versions before install.

Stable:

bunx @lucid-agents/[email protected] my-service \
  --adapter=hono \
  --template=blank

Current repository (Next):

bun run build:packages
bun packages/cli/dist/index.js my-service \
  --adapter=hono \
  --ui-preset=folio \
  --template=blank \
  --no-install

Do not use @latest in reproducible automation. Repository templates track the Next workspace and are not proof that the same package versions are available on npm.

Templates

| Template | Purpose | Adapters | | ------------------------------ | ------------------------------------------------------------- | -------------------------------------------- | | blank | Minimal typed service and starting capability | Hono, Express, TanStack UI/headless, Next.js | | identity | Wallet, ERC-8004 identity metadata/registration, and payments | Hono, Express, TanStack UI/headless, Next.js | | trading-data-agent | Legacy merchant example; requires v3 template migration | Hono, Express | | trading-recommendation-agent | Legacy buyer example; requires v3 template migration | Hono, Express |

The generated-project verification matrix currently covers blank across all five adapters. The two trading templates still contain pre-v3 composition and are not a supported starting point until their generated source, dependencies, and paid task calls are migrated and added to that matrix. Their documentation records the target contract. They are also not a claim of conformance with the official A2A v1 transport or task model.

Adapters

| Adapter | Generated shape | | ------------------- | ----------------------------------------------------------------------------------------------------- | | hono | Hono application plus a static, read-only public storefront | | express | Express application plus a static, read-only public storefront | | tanstack-ui | TanStack Start routes plus a public service storefront | | tanstack-headless | TanStack Start routes without the storefront | | next | Next.js App Router modules plus the shared storefront; there is no standalone Next.js adapter package |

The generated UI is a minimal, read-only endpoint directory. Every invoke and stream operation appears in a table with its HTTP path, payment method, and price. Detailed schemas and the complete Agent Card remain available from the public API rather than being repeated as JSON in the page. TanStack headless deliberately generates neither the directory nor its config.

Every UI-capable adapter writes one editable service-ui.config.ts. Choose dossier (dark mono), folio (light editorial), or console (compact dark). The file supports only validated semantic color and font tokens; all presets keep the same endpoint-table layout.

Options

Usage: bunx @lucid-agents/cli <app-name> [options]

  -t, --template <id>   Select a template
  -a, --adapter <id>    Select an adapter
  -i, --install         Run bun install after scaffolding
  --no-install          Skip installation (default)
  --no-deploy           Omit deployment tooling and configuration
  --wizard=no           Use template defaults
  --no-wizard           Alias for --wizard=no
  --non-interactive     Alias for --wizard=no
  --ui-preset <id>      Select dossier, folio, or console
  --network=<network>   Map a payment-network value to PAYMENTS_NETWORK
  --KEY=value           Supply a template wizard value in non-interactive mode
  -h, --help            Show installed CLI help

--framework is accepted as a compatibility alias for --adapter.

Reproducible non-interactive generation

Supply the template, adapter, and every deployment-sensitive value. Prefer a canonical CAIP-2 network even though the wizard accepts historical aliases.

bunx @lucid-agents/[email protected] paid-service \
  --adapter=hono \
  --template=blank \
  --non-interactive \
  --no-install \
  --AGENT_DESCRIPTION='Paid analysis service' \
  --AGENT_VERSION='0.1.0' \
  --PAYMENTS_FACILITATOR_URL='https://YOUR_TESTNET_FACILITATOR' \
  --PAYMENTS_NETWORK='eip155:84532' \
  --PAYMENTS_DESTINATION='static' \
  --PAYMENTS_RECEIVABLE_ADDRESS='0xYOUR_EVM_ADDRESS'

Then:

cd paid-service
sed -n '1,200p' .env.example
bun install
bunx tsc --noEmit
bun run dev

Review the generated package.json, .env.example, entrypoint prices, public origin/base path, and facilitator before deploying. A template default is not a production provider recommendation.

There is no PAYMENTS_DEFAULT_PRICE runtime variable. Prices belong on each entrypoint as USD decimal strings. The wallet helper uses role-specific names such as AGENT_WALLET_PRIVATE_KEY and DEVELOPER_WALLET_PRIVATE_KEY; a generic PRIVATE_KEY is not the current documented contract.

Wizard behavior

1. The CLI selects a compatible adapter and template.
2. --KEY=value answers are used only in non-interactive/skip-wizard mode.
3. Unspecified answers fall back to defaultValue in the template's template.json.
4. Conditional prompts are included only when their when rule matches.
5. Sensitive inputs are collected without terminal echo and do not display a default value.
6. Stripe destination mode forces the generated payment network to Base.
7. UI-capable adapters select a storefront preset and write the typed root service-ui.config.ts file.
8. The resolved context and wizard answers must satisfy the template's template.schema.json; invalid versions, URLs, networks, and conditional safety requirements fail before staging begins.
9. Adapter files and template sections are composed in a staging directory.
10. .env and .env.example are generated, .env is written with owner-only 0600 permissions and gitignored, and template metadata is removed.
11. Dependencies are installed only with --install.
12. The completed staging directory replaces the empty target only after every requested step succeeds.

The target directory must be absent or empty. Invalid arguments, generation errors, and dependency-install failures leave it unchanged and return a failure. Scaffolding directly into the current working directory (. or an equivalent path) is rejected because it cannot use the same atomic directory handoff; choose a new child directory instead. If no project name is supplied, the CLI derives one from the selected template.

Generated project contract

The exact files vary by adapter, but every project should keep these boundaries:

• one completed Lucid runtime owns the canonical entrypoint registry;
• @lucid-agents/http owns payment/SIWX authorization and route handlers;
• the framework adapter binds those routes instead of adding another paywall;
• private configuration stays server-side; and
• public storefronts derive data from Agent Card and health handlers.

After generation, add one capability at a time and test:

bunx tsc --noEmit
curl -i http://localhost:3000/health
curl -i http://localhost:3000/.well-known/agent-card.json

For a priced route, verify the unpaid request returns x402 402 before funding a buyer. Use the repository's Stable quickstart for the complete paid loop.

Deployment-ready blank Hono projects

The current repository scaffold makes the blank + hono combination Cloudflare-ready by default. It adds a separate fetch-native Worker entry, wrangler.jsonc, a versioned lucid.deploy.json, and the bun run deploy command while preserving the normal Bun server for local development.

bunx wrangler login
bun run deploy

The default command uploads a Worker version with a preview alias and never deploys production. @lucid-agents/deploy uploads only manifest-allowlisted environment values, uses Worker secrets for secret-classified values, forces preview identity auto-registration off, prints a redacted plan, and verifies the landing page, health endpoint, and canonical Agent Card at the returned URL. CI requires both CLOUDFLARE_API_TOKEN and --yes.

Pass --no-deploy while scaffolding to omit the deploy package, Wrangler, Worker entry, manifest, provider configuration, command, and deployment README section. Other template/adapter combinations remain unchanged until their provider drivers are added.

Template development

Template source lives in packages/cli/templates/; framework assets live in packages/cli/adapters/. When changing either:

bun run --cwd packages/cli build
bun test packages/cli/tests

Generate every compatible adapter/preset pair with --no-install, inspect the transformed files, then install/type-check the changed combinations. The CI matrix covers 12 UI combinations plus one headless project. UI cases receive a deterministic kitchen-sink Agent Card after scaffolding so schemas, streaming, tasks, SIWX, x402, MPP, AP2, trust, and security stay portable together. Update the template schema, AGENTS.md, and README when adding wizard keys or public behavior.

Programmatic API

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

Troubleshooting

• Unknown template/adapter: run --help and choose a compatible pair.
• Target exists: choose an empty directory; the CLI does not merge into an existing tree.
• Generated install fails: inspect package versions before running bun install; do not mix Stable and Next packages. A failed --install leaves no partial project, so rerun with --no-install when you need to inspect or repair dependency resolution manually.
• Priced route is free: confirm the entrypoint has an explicit price and the matching payment extension/configuration is installed.
• Identity registration fails: identity uses an EVM developer/agent signer even when the service receives x402 payments on Solana.

See the public CLI reference, release channels, and environment inventory.

Contributing

See CONTRIBUTING.md.