> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/wokwi/wokwi-docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Wokwi CLI Usage

> Wokwi CLI command reference and usage guide.

Create an API token on the [Wokwi CI Dashboard](https://wokwi.com/dashboard/ci). 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:

```bash theme={null}
wokwi-cli init
```

This command will ask you a few questions and will automatically generate [wokwi.toml](../vscode/project-config) and [diagram.json](../diagram-format) files for your project.

## Run a Simulation

To run the simulation, use the following command:

```bash theme={null}
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

<ParamField path="--elf" type="string">
  ELF file to simulate (default: read from wokwi.toml)
</ParamField>

<ParamField path="--diagram-file" type="string">
  Path to the diagram.json file, relative to project root (default: diagram.json)
</ParamField>

<ParamField path="--interactive" type="boolean">
  Redirect stdin to the simulated serial port
</ParamField>

<ParamField path="--serial-log-file" type="string">
  Save the serial monitor output to the given file
</ParamField>

<ParamField path="--timeout" type="number">
  Timeout in simulation milliseconds (default: 30000)
</ParamField>

<ParamField path="--timeout-exit-code" type="number">
  Process exit code when timeout is reached (default: 42)
</ParamField>

### Automation

<ParamField path="--expect-text" type="string">
  Expect the given text in the output
</ParamField>

<ParamField path="--fail-text" type="string">
  Fail if the given text is found in the output
</ParamField>

<ParamField path="--scenario" type="string">
  Path to an [automation scenario](./automation-scenarios) file, relative to project root
</ParamField>

<ParamField path="--screenshot-part" type="string">
  Take a screenshot of the given part id (from diagram.json)
</ParamField>

<ParamField path="--screenshot-time" type="number">
  Time in simulation milliseconds to take the screenshot
</ParamField>

<ParamField path="--screenshot-file" type="string">
  File name to save the screenshot to (default: screenshot.png)
</ParamField>

<ParamField path="--vcd-file" type="string">
  Export [Logic Analyzer](../parts/wokwi-logic-analyzer) data to a VCD file
</ParamField>

### General

<ParamField path="--help" type="boolean">
  Prints help information and exit (alias: `-h`)
</ParamField>

<ParamField path="--quiet" type="boolean">
  Quiet: do not print version or status messages (alias: `-q`)
</ParamField>

## Linting Diagrams

The `lint` command validates your [diagram.json](../diagram-format) file for errors and warnings before running a simulation:

```bash theme={null}
wokwi-cli lint
```

<Note>
  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.
</Note>