MPLAB CLI

Preview Notice: This is an alpha (preview) version of the MPLAB CLI. Features and APIs are subject to change. Please report any issues or feedback.

The MPLAB CLI can be used to manage and build projects created by MPLAB for VS Code.

✨ Features

• Build MPLAB projects
• Output MPLAB project info
• Create and modify MPLAB projects
• Import projects created by MPLAB X IDE and Microchip Studio for AVR and SAM Devices
• Install support applications and toolchains
• Install device and tool packs

🚀 Installation

Using npm:

npm install -g @mplab/cli

Using yarn:

yarn global add @mplab/cli

Once installed you can verify the installation by running --help which lists available commands:

mplab --help

To get detailed help on a specific command (example project) run:

mplab project --help

▶️ Running Without Installing

You can run the MPLAB CLI directly without a global installation using a package manager executor:

Using npx (npm):

npx @mplab/cli --help

Using yarn dlx (yarn 2+):

yarn dlx @mplab/cli --help

Using pnpx (pnpm):

pnpx @mplab/cli --help

Using bunx (bun):

bunx @mplab/cli --help

🔨 Building projects

Install prerequisites

Building projects requires CMake and Ninja to be installed. If you do not have this installed (needs to be available from the PATH environmental variable) you can install them by running:

mplab app install cmake
mplab app install ninja

Install packs for project

Projects depend on one or more device packs. They must be available before compiling a project. To install all packs required by a given project run:

mplab packs install --project myProject.mplab.json

Build project

To build a project:

mplab project build myProject.mplab.json

📦 Packs

Packs are downloaded and shared with MPLAB for VS Code. To use a custom location you can add the --packFolder parameter or you can set it using the environmental variable MPLAB_PACKS_HOME.

Get info about available and installed packs for devices and tools:

mplab packs info --device ATtiny817
mplab packs info --tool Simulator;

Install specific packs using latest or specific version and or specific vendor:

mplab packs install --pack ATtiny_DFP
mplab packs install --pack [email protected]
mplab packs install --pack [email protected]
mplab packs install --pack CMSIS
mplab packs install --pack [email protected]

Install latest pack for a given device or tool:

mplab packs install --device ATtiny817
mplab packs install --tool Simulator

Install all packs (DFPs and CMSIS) required by all configurations in a given MPLAB project file:

mplab packs install --project My_Project.mplab.json

🗂️ Applications

Applications are downloaded and shared with MPLAB for VS Code. To use a custom location you can use the --appFolder parameter or you can set it using the environmental variable MPLAB_APP_FINDER_HOME.

Get a list of installed compilers and binaries downloaded by the MPLAB VS Code Extensions:

mplab app list installed

Install applications. (Example installs latest versions of CMake and Ninja)

mplab app install cmake
mplab app install ninja

⚙️ Project management

Import an MPLAB X project:

mplab project import C:\Users\MPLABXProjects\project.X

Workspace Configuration: By default, the .vscode folder is created in your current working directory. You can override this with the --workspace flag or configure a global default:

# Use a specific workspace directory
mplab project import project.X --workspace /path/to/workspace

# Set global default to current working directory (default behavior)
mplab config set import.workspace.default cwd

# Set global default to project directory (legacy behavior)
mplab config set import.workspace.default project-dir

The precedence is: --workspace flag > config file > default (cwd).

Create a new MPLAB project:

mplab project create --device ATtiny817 myProject

Add a new configuration:

mplab project add-config myProject.mplab.json new-config

Show information about configurations:

mplab project info myProject.mplab.json configs

Update project by setting all DFPs and toolchain to latest:

mplab project set pack latest myProject.mplab.json
mplab project set toolchain latest myProject.mplab.json

Update project by setting specific DFP and toolchains:

mplab project set pack ATtiny_DFP@latest myProject.mplab.json
mplab project set pack [email protected] myProject.mplab.json
mplab project set toolchain [email protected] myProject.mplab.json
mplab project set toolchain xc8@latest myProject.mplab.json

Change a device:

mplab project set device ATtiny817 myProject.mplab.json

Change a toolchain parameter:

mplab project set toolchain-property optimization-level=-O3 myProject.mplab.json

🤖 CI/CD Automation

This section provides an example of how to import and build projects using the CLI in a CI/CD setting (for example, inside a Docker image or a build agent).

For more details on each command use mplab --help.

Build environment prerequisites

The build environment (for example, a Docker image) should include the following:

• Node.js (version 20.16 or higher) and npm
• A toolchain installation matching the version used in the project

Install the CLI

npm install -g @mplab/cli

Install cmake and ninja

mplab app install cmake --appFolder /tmp/myApps
mplab app install ninja --appFolder /tmp/myApps

Alternatively, use custom cmake and ninja installations as long as they are available on the PATH environment variable.

Import an MPLAB X project

cd /home/MPLABXProjects/Project.X
mplab project import . --projectFileName myProject.mplab.json

Install packs required by the project

mplab packs install --project ./.vscode/myProject.mplab.json --packFolder /tmp/myPacks

Build the project

Assuming the configuration name in the imported project is default:

mplab project build ./.vscode/myProject.mplab.json default --appFolder /tmp/myApps --packFolder /tmp/myPacks

⚠️ Known Issues

Build & Compilation

• DFP/Device Support Files Not Passed Correctly

  • Build fails with "no device-support files specified" or missing -mdfp option even when DFP is configured in project settings
  • Affects: Various devices and toolchains

• Per-File Compiler Options Not Applied

  • Custom per-file compiler flags (warnings, optimization overrides) set in project XML are not converted to CMake build flags
  • Affects: XC8, XC16 toolchains

• Conflicting Debug Format Flags for AVR Devices

  • XC8 builds for ATtiny/AVR generate both -gdwarf-2 and -gcoff flags causing "debug format conflicts" errors
  • Affects: ATtiny, AVR devices with XC8

Platform-Specific Issues

• macOS: Wrong Toolchain Options for AVR Projects

  • AVR projects on macOS incorrectly receive PIC toolchain options instead of AVR options; works correctly on Linux/Windows
  • Affects: macOS, AVR devices

• Linux: Per-File Options Missing

  • XC16 per-file override options are generated correctly on Windows but missing on Linux for the same project
  • Affects: Linux, XC16

Toolchain & Pack Management

• Pack Download Intermittent Failures

  • Pack installation via CLI may intermittently fail with "Unable to get a Product Release" error
  • Workaround: Retry or use VS Code UI to download packs

• Not All Installed Toolchains Detected

  • CLI may not detect all installed toolchain versions (e.g., shows only one avr-gcc version when multiple are in PATH)
  • Affects: AVR-GCC

🐞 Feedback and issue reporting

Go to mplabfeedback.microchip.com to report issues and suggest enhancements.

📝 License Information

To review the complete terms and conditions governing the use of this software, please consult the "license" file included with this package.

Copyright © 2026 Microchip