This CLI tool simplifies the process of developing applications and interacting with ZKsync.
- Prerequisites
- Usage
- Commands List
- Supported Chains
- Developing New Features
- Official Links
- License
- Troubleshooting
- Node.js v18 or higher
- Git
- Docker (for
zksync-cli dev
commands)
You can run commands without installation: npx zksync-cli
. For example: npx zksync-cli dev start
.
npx zksync-cli dev
- Manage local ZKsync development environment. It allows to easily start ZKsync stack locally, for example: local Ethereum and ZKsync nodes, Block Explorer, Wallet and Bridge.
npx zksync-cli dev start
- start local development environment (will ask to configure if starting for the first time)npx zksync-cli dev clean
- clean data for configured modulesnpx zksync-cli dev config
- select modules to run in local development environment
Run npx zksync-cli dev
to see the full list of commands.
npx zksync-cli create
: Create a project using updated templates.- Frontend: Rapid UI development with templates for Vue, React, Next.js, Nuxt, Vite, etc. Options include viem, ethers, web3modal, rainbowkit. More Info
- Contracts: Quick contract deployment and testing with tools like Hardhat on Solidity or Vyper. Contract templates
- Scripting: Automated interactions and advanced ZKsync operations using Node.js, with examples of wallet or contract interactions using viem, ethers or web3.js. Scripting Templates
See full documentation and advanced examples here.
npx zksync-cli contract read
: run read-only contract methodsnpx zksync-cli contract write
: send transactions to the contractnpx zksync-cli contract encode
: get calldata from the contract method
See full documentation and advanced examples here.
npx zksync-cli transaction info
: get information about a transaction
npx zksync-cli wallet transfer
: send funds on L2 to another accountnpx zksync-cli wallet balance
: displays token balance of the specified address
npx zksync-cli bridge deposit
: deposits funds from Ethereum (L1) to ZKsync (L2)npx zksync-cli bridge withdraw
: withdraws funds from ZKsync (L2) to Ethereum (L1)npx zksync-cli bridge withdraw-finalize
: finalizes withdrawal of funds from ZKsync (L2) to Ethereum (L1)
npx zksync-cli config chains
: Add or edit custom chainsnpx zksync-cli help
: Provides information about all supported commandsnpx zksync-cli <command> --help
: Provides detailed information about how to use a specific command. Replace <command> with the name of the command you want help with (e.g.,create
,dev config
,bridge withdraw-finalize
)npx zksync-cli --version
: Returns the current version
Note: currently you might face issues interacting with custom ZK Chains. Fix is in progress. By default zksync-cli bridge commands support ZKsync Sepolia Testnet and ZKsync Mainnet. You can also use other networks by using one the options below:
- Adding custom chain using
npx zksync-cli config chains
command. - Overwriting L1 and L2 RPC URLs. For example:
npx zksync-cli deposit --rpc=http://... --l1-rpc=http://...
If you're using local setup (dockerized testing node) with default L1 and L2 RPC URLs, you can select Local Dockerized node
option in the CLI or provide option --chain local-dockerized
.
- Install all dependencies with
npm i
. - To use CLI in development mode run
npm run dev -- [command] [options]
(e.g.npm run dev -- bridge deposit --chain=zksync-sepolia
).
- Install all dependencies with
npm i
. - This project was build with Typescript. Run
npm run build
to compile the code into/bin
. - You can run your local build with
node ./bin
At the moment, we don't have any tests, but we are working on it. In the meantime, you can test the code manually by running the code in development mode.
This project is licensed under MIT.
Encountering issues with zksync-cli? Below are some common problems with step-by-step recommendations for resolving them:
`unknown command` Error
If you encounter an unknown command
error, follow these steps:
a. Check the zksync-cli Version
- Run
npx zksync-cli --version
to check your current version. - Compare it with the latest version available on npm.
- If your version is lower than the one on npm follow the steps bellow. If your version is up-to-date, it's possible that the command was moved or renamed. Use
npx zksync-cli help
for a list of current commands or refer to the documentation.
b. Verify Local Installation
- Use
npm list zksync-cli
to check ifzksync-cli
is installed in the current directory or any parent directories from where you are running your terminal. - If it is indeed installed, make sure to uninstall it by running
npm uninstall zksync-cli
in its installation location. Remove all instances ofzksync-cli
until there are no more found bynpm list zksync-cli
.
c. Verify Global Installation
- Use
npm list -g zksync-cli
to check ifzksync-cli
is installed globally. - If it is installed globally, uninstall it using
npm uninstall -g zksync-cli
.
d. Clean npm Cache
- Run
npm cache clean --force
.
e. Use the Latest Version
- As a quick fix, or if the above steps don't resolve the issue, use
npx zksync-cli@latest [command]
, for example,npx zksync-cli@latest dev start
.
My Version is Outdated
If npx zksync-cli
is not running the latest version:
- Refer to the guide above to check and update your zksync-cli version.
`command not found: npx` Error
If you receive a command not found: npx
error, it means Node.js is not installed or not correctly set up on your system:
- Install Node.js from https://nodejs.org/. This will also install
npm
andnpx
. - After installation, restart your terminal and try running
npx zksync-cli
again.
For all other issues, we encourage you to ask for help or report them in our GitHub Discussions.