This guide is divided into five sections:
- How to use and interact with the CLI.
- Running a basic CLI functionality check.
- Ensuring the CLI is properly installed and configured.
- Steps to take if the CLI does not recognize your device.
- How to report CLI-related issues (important!).
But first, let's ensure that you've installed Particle's Command Line Interface (CLI) by following the instructions here: (link).
1. How to use and interact with the CLI:
Right off the bat, you may be reading this article with a more conceptual question: how do I actually access the Particle CLI and run commands?
CLI stands for "Command Line Interface" - one accesses the CLI via your computer's command line.
For MacOS, use your computer's Spotlight Search to search for "Terminal".
For Windows, perform a search for "cmd.exe".
You will be confronted with something that looks like this:
2. Running a basic CLI functionality check:
Before troubleshooting further, please take the following steps to ensure the CLI's basic operations are functional. Try running:
particle login(ensure the CLI can complete the login process)
particle usb list(ensure that no errors are reported. If no devices are connected via USB, this command will report 0. If it fails with an error like this (link), confirm that your OS / CPU architecture are supported - as of writing this, some ARM environments are not fully supported).
particle serial list(ensure that no errors are reported. If no devices are connected for serial communication via USB, this command will report 0).
If you receive errors from the above, it's worth proceeding further through this guide. If these commands report as expected, it's worth taking a good look at our CLI reference page (link) to ensure that the commands you are trying to run are supported and formatted correctly.
3. Ensuring the CLI is properly installed on and configured for your system:
Issues related to build tools can be complex! After all, every computer is configured differently and is governed by unique administrative permissions schema, firewalls, networking settings, etc.... The majority of CLI issues are related to this complexity, so taking a step back and ensuring your tools are installed and configured properly is an important step to the troubleshooting process.
- Verify you are using the latest version of the CLI - there’s a decent chance we’ve already fixed your issue. You can use the command
particle update-clivia the command line.
- Disable Antivirus Software - some antivirus programs interfere with the CLI. During the course of troubleshooting, it is important to temporarily disable or explicitly grant higher privileges in your firewall interface to confirm your issue is still present.
- Likewise, temporarily disable any VPNs through which you may be networking and confirm that your issue is still present.
- Avoid Network Storage Drives targeting a project in a Dropbox / OneDrive / Google Drive directory. Ensure the CLI has been installed within a standard directory to which you have the appropriate permissions.
- If you are receiving errors from CLI functions, do ensure that you have correctly logged into the CLI by using
From there, take the following steps to reset your CLI installation:
Open the directory containing the CLI’s files:
- MacOS / Linux:
- MacOS / Linux:
Delete the following files and directories if available:
Update the CLI:
- run the
Particle: Update CLIcommand
If stand-alone CLI
- Open a terminal (Powershell, Cmd.exe, Bash, Zsh, etc..).
particle update-cliand wait for the operation to complete.Reset your CLI installation:
Once that completes, confirm a successful reinstallation by by running the
particle usb list and
particle serial inspect CLI commands (or, n Workbench, run
Particle: Launch CLI and type the aforementioned commands into the terminal pane that launches).
4. Steps to take if the CLI does not recognize your device:
Hardware peripheral issues have several main causes. In order:
- Investigate your USB cable. 90%+ of cases where the CLI cannot detect your device result from two major cable issues. First, make sure your USB cable is a data cable (not simply a power cable). There are, unfortunately, no conventions around labeling cables as data cables or power cables - the easiest way to ensure your USB cable is in fact a data cable is to attempt to transmit data to it. We recommend cross-testing against another device and against another cable. Following the PuTTY/CoolTerm instructions here (link) is an easy way to test a viable USB serial connection to your device without using the CLI.
- Make sure your USB cable is not damaged in some way. Again, cross-testing against another device and against another cable is strongly recommended.
- Bypass USB hub / extensions - if you are working with a device and are seeing issues related to its USB connection, try disconnecting all USB devices and reconnecting only your Particle device directly to you computer’s USB port.
- For Windows devices, you may need to ensure that the appropriate drivers are installed. IF you see the error
LIBUSB_ERROR_NOT_SUPPORTED, you may need to install the latest Particle USB/serial drivers. Please see our extensive troubleshooting documentation for fixing Windows driver issues here: (link).
- Check your computer's Device Manager to ensure that your computer is able to identify the device. For MacOS, you will need to go to
Applications/Utilitiesand open up the application called "System Information." For Windows, this is your Device Manager.
When in DFU mode, the Device Manager looks like this: (Note that it may say Photon DFU Mode regardless of device type.)
And when in normal operating mode or listening mode (blinking blue), the Device Manager looks like this:
- If your device is recognized in DFU Mode but not in any other mode, you may need to perform an update to that device in order for it to recognize Serial commands. In order to do so, as always, place the device in DFU Mode (hold down BOTH buttons, then release only the
RESETbutton, while holding down the
MODEbutton. Wait for the LED to start flashing yellow (it will flash magenta first) and release the
MODEbutton once it's flashing yellow). Then run the CLI commands
particle updatefollowed by
particle flash --usb tinker.
5. How to report CLI issues:
Particle's Support Team refers CLI and Workbench issues to our Particle Community (link). There are several benefits to doing so - other members of our Community may already have a solution for this issue, it allows for more transparent self-service after your issue is resolved, and it also is an often direct channel to our CLI and Workbench Engineering Team. In order to report your issue, please post in our Particle Community (link) following the instructions below:
- Capture verbose error logs of the incident in question - run your any commands that have been failing using the
--verboseflag (- e.g.
particle <cmd> --verbose) and collect those results into your report.
- Collect the contents of your particle directory -
ls -a ~./particle(MacOS / Linux), or
get-childitem ~\AppData\Local\particle(Windows + PowerShell) into your report as well.
- Navigate to the Particle Community's CLI Topic (link) and post your issue, taking care to further specify:
- Operating System
- CPU Architecture (32/64 bit? ARM?)
- CLI Version (
- CLI Installation Type (Standard or Advanced?, see link: (here).
- Terminal / Shell within which you running the Particle CLI (e.g. Powershell, Bash, Zsh, cmd.exe, etc)
- What Particle hardware are you using (Argon, Boron, etc...) and with what Device OS Version?
- Carefully, with screenshots as appropriate, walk us through the process with which you experience the error step-by-step, taking care to note expected behavior.
- Ensure you use the [ISSUE] Prefix in your Community Post so as to draw our attention to the post.