Skip to main content

​
Introduction

The create-lz-oapp CLI is a powerful command-line tool designed to streamline the development of 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 NameDescription
oappOApp: Basic Omnichain Application for crosschain messaging
oftOFT: Omnichain Fungible Token implementation
oft-adapterOFTAdapter: Adapter for existing ERC20 tokens
onft721ONFT721: Omnichain Non-Fungible Token (ERC721)

​
Feature-Flagged Examples

These examples are available only when specific environment variables are set:
Example NameDescriptionRequired Environment Variable
lzapp-migrationEndpointV1 MigrationLZ_ENABLE_MIGRATION_EXAMPLE
onft721-zksyncONFT721 zksolcLZ_ENABLE_ZKSOLC_EXAMPLE
oft-upgradeableUpgradeableOFTLZ_ENABLE_UPGRADEABLE_EXAMPLE
native-oft-adapterNativeOFTAdapterLZ_ENABLE_NATIVE_EXAMPLE
oft-altOFTAltLZ_ENABLE_ALT_EXAMPLE
mint-burn-oft-adapterMintBurnOFTAdapterLZ_ENABLE_MINTBURN_EXAMPLE
oapp-readlzRead View/Pure Functions ExampleLZ_ENABLE_READ_EXAMPLE
view-pure-readlzRead Public Variables ExampleLZ_ENABLE_READ_EXAMPLE
uniswap-readlzRead UniswapV3 QuoteLZ_ENABLE_READ_EXAMPLE
oft-solanaOFT (Solana)LZ_ENABLE_SOLANA_OFT_EXAMPLE
oapp-solanaOApp (Solana)LZ_ENABLE_SOLANA_OAPP_EXAMPLE
oft-initiaOFT (Initia)LZ_ENABLE_EXPERIMENTAL_INITIA_EXAMPLES
oft-adapter-initiaOFT Adapter (Initia)LZ_ENABLE_EXPERIMENTAL_INITIA_EXAMPLES
oft-aptos-moveOFT (Aptos Move)LZ_ENABLE_EXPERIMENTAL_MOVE_VM_EXAMPLES
oft-adapter-aptos-moveOFT Adapter (Aptos Move)LZ_ENABLE_EXPERIMENTAL_MOVE_VM_EXAMPLES
oapp-aptos-moveOApp (Aptos Move)LZ_ENABLE_EXPERIMENTAL_MOVE_VM_EXAMPLES
oft-hyperliquidOFT + Composer (Hyperliquid)LZ_ENABLE_EXPERIMENTAL_HYPERLIQUID_EXAMPLE
omni-callEVM OmniCallLZ_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.