create-lz-oapp CLI guide

Introduction

The create-lz-oapp CLI is a command-line tool for scaffolding LayerZero Omnichain Applications (OApps). This CLI toolkit simplifies the process of building, testing, deploying, and configuring omnichain applications by providing a structured project template and essential development tools. With create-lz-oapp, you can quickly bootstrap a new LayerZero project with both Hardhat and Foundry development frameworks pre-configured, along with example contracts, crosschain unit tests, LayerZero configuration files, and deployment scripts.

Installation & Usage

Create a new LayerZero OApp project with a single command:

npx create-lz-oapp@latest

This will launch an interactive project creation wizard that guides you through setting up your omnichain application.

CLI Options

The create-lz-oapp CLI supports the following options:

Version Information

-V, --version

Output the current version number of the CLI tool.

CI Mode

--ci

Run the CLI in CI (Continuous Integration) mode, which operates in non-interactive mode. This is useful for automated deployments and scripts where user interaction is not available.

Default: false

Project Directory

-d, --destination <path>

Specify the target directory where the new project should be created. If not provided, the CLI will use the current directory or prompt for a location.

Example Project Template

-e, --example <name>

Choose which example project template to use as the starting point for your application.

Always Available Examples

These examples are always available:

Example Name	Description
`oapp`	OApp: Basic Omnichain Application for crosschain messaging
`oft`	OFT: Omnichain Fungible Token implementation
`oft-adapter`	OFTAdapter: Adapter for existing ERC20 tokens
`onft721`	ONFT721: Omnichain Non-Fungible Token (ERC721)

Feature-Flagged Examples

These examples are available only when specific environment variables are set:

Example Name	Description	Required Environment Variable
`lzapp-migration`	EndpointV1 Migration	`LZ_ENABLE_MIGRATION_EXAMPLE`
`onft721-zksync`	ONFT721 zksolc	`LZ_ENABLE_ZKSOLC_EXAMPLE`
`oft-upgradeable`	UpgradeableOFT	`LZ_ENABLE_UPGRADEABLE_EXAMPLE`
`native-oft-adapter`	NativeOFTAdapter	`LZ_ENABLE_NATIVE_EXAMPLE`
`oft-alt`	OFTAlt	`LZ_ENABLE_ALT_EXAMPLE`
`mint-burn-oft-adapter`	MintBurnOFTAdapter	`LZ_ENABLE_MINTBURN_EXAMPLE`
`oapp-read`	lzRead View/Pure Functions Example	`LZ_ENABLE_READ_EXAMPLE`
`view-pure-read`	lzRead Public Variables Example	`LZ_ENABLE_READ_EXAMPLE`
`uniswap-read`	lzRead UniswapV3 Quote	`LZ_ENABLE_READ_EXAMPLE`
`oft-solana`	OFT (Solana)	`LZ_ENABLE_SOLANA_OFT_EXAMPLE`
`oapp-solana`	OApp (Solana)	`LZ_ENABLE_SOLANA_OAPP_EXAMPLE`
`oft-initia`	OFT (Initia)	`LZ_ENABLE_EXPERIMENTAL_INITIA_EXAMPLES`
`oft-adapter-initia`	OFT Adapter (Initia)	`LZ_ENABLE_EXPERIMENTAL_INITIA_EXAMPLES`
`oft-aptos-move`	OFT (Aptos Move)	`LZ_ENABLE_EXPERIMENTAL_MOVE_VM_EXAMPLES`
`oft-adapter-aptos-move`	OFT Adapter (Aptos Move)	`LZ_ENABLE_EXPERIMENTAL_MOVE_VM_EXAMPLES`
`oapp-aptos-move`	OApp (Aptos Move)	`LZ_ENABLE_EXPERIMENTAL_MOVE_VM_EXAMPLES`
`oft-hyperliquid`	OFT + Composer (Hyperliquid)	`LZ_ENABLE_EXPERIMENTAL_HYPERLIQUID_EXAMPLE`
`omni-call`	EVM OmniCall	`LZ_ENABLE_EXPERIMENTAL_OMNI_CALL_EXAMPLE`

Log Level

--log-level <level>

Set the verbosity level for CLI output and logging information.

Available choices: "error", "warn", "info", "http", "verbose", "debug", "silly"
Default: "info"

Package Manager

-p, --package-manager <name>

Choose which Node.js package manager to use for dependency management in your project.

Available choices: "npm", "pnpm", "bun"

Environment Variables for Feature-Flagged Examples

To access feature-flagged examples, you can set the corresponding environment variables inline with the command. These examples provide access to experimental, specialized, or advanced features.

Setting Environment Variables

On Unix/macOS/Linux:

LZ_ENABLE_READ_EXAMPLE=1 npx create-lz-oapp@latest -e oapp-read

On Windows (Command Prompt):

set "LZ_ENABLE_READ_EXAMPLE=1" && npx create-lz-oapp@latest -e oapp-read

On Windows (PowerShell):

$env:LZ_ENABLE_READ_EXAMPLE=1; npx create-lz-oapp@latest -e oapp-read

Example Usage

Basic Interactive Setup

npx create-lz-oapp@latest

Non-Interactive Setup with Options

npx create-lz-oapp@latest --ci -d ./my-oapp-project -e oapp -p pnpm --log-level verbose

Create an OFT Project

npx create-lz-oapp@latest -e oft -d ./my-oft-token -p pnpm

Create an ONFT721 Project

npx create-lz-oapp@latest -e onft721 -d ./my-nft-project -p pnpm

Using Feature-Flagged Examples

To use feature-flagged examples, include the required environment variable in the command:

# Enable lzRead examples and create an lzRead project
LZ_ENABLE_READ_EXAMPLE=1 npx create-lz-oapp@latest -e oapp-read -d ./my-read-project -p pnpm

# Enable Solana examples and create a Solana OFT project
LZ_ENABLE_SOLANA_OFT_EXAMPLE=1 npx create-lz-oapp@latest -e oft-solana -d ./my-solana-oft -p pnpm

# Enable upgradeable examples in CI mode
LZ_ENABLE_UPGRADEABLE_EXAMPLE=1 npx create-lz-oapp@latest --ci -e oft-upgradeable -d ./upgradeable-oft -p bun

Next Steps

After creating your project with create-lz-oapp, you’ll have a fully structured omnichain application ready for development. The generated project includes:

Example smart contracts implementing LayerZero standards
Deployment scripts and configuration

The project structure will vary depending on the example template you selected, with each template providing the appropriate contracts, tests, and configuration for that specific use case (OApp, OFT, ONFT, etc.). Refer to the generated project’s README file for specific instructions on how to configure, test, and deploy your omnichain application.

Tools Overview

MCP Server

Integration

Simple Config Generator