Wokwi CLI Usage

Wokwi CLI command reference and usage guide.

Create an API token on the Wokwi CI Dashboard. Set the WOKWI_CLI_TOKEN environment variable to the token value.

Initialize Your Project

If you haven’t set up your project for Wokwi yet, you can use the init command to configure your project for Wokwi. Run the following command in your project’s root directory:

wokwi-cli init

This command will ask you a few questions and will automatically generate wokwi.toml and diagram.json files for your project.

Run a Simulation

To run the simulation, use the following command:

wokwi-cli <your-project-directory>

The CLI will start the simulation and display the serial output. It will automatically exit after 30 seconds.

CLI Options

You can use the following options to customize the CLI behavior:

Configuration

--elf · string

ELF file to simulate (default: read from wokwi.toml)

--diagram-file · string

Path to the diagram.json file, relative to project root (default: diagram.json)

--interactive · boolean

Redirect stdin to the simulated serial port

--serial-log-file · string

Save the serial monitor output to the given file

--timeout · number

Timeout in simulation milliseconds (default: 30000)

--timeout-exit-code · number

Process exit code when timeout is reached (default: 42)

Automation

--expect-text · string

Expect the given text in the output

--fail-text · string

Fail if the given text is found in the output

--scenario · string

Path to an automation scenario file, relative to project root

--screenshot-part · string

Take a screenshot of the given part id (from diagram.json)

--screenshot-time · number

Time in simulation milliseconds to take the screenshot

--screenshot-file · string

File name to save the screenshot to (default: screenshot.png)

--vcd-file · string

Export Logic Analyzer data to a VCD file

General

--help · boolean

Prints help information and exit (alias: -h)

--quiet · boolean

Quiet: do not print version or status messages (alias: -q)

Linting Diagrams

The lint command validates your diagram.json file for errors and warnings before running a simulation:

wokwi-cli lint

The linter checks for common issues such as unknown part types, invalid pin connections, and missing components. By default, it fetches the latest board definitions from the Wokwi registry to ensure accurate validation.