create-lz-oapp CLI Guide
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, cross-chain 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 cross-chain 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.