Command Reference

Parameter Types

query

A vendor:model:serial string that specifies one or more connected USB CircuitPythonDevice. Each component string is searched for in the respective attribute. Empty strings are allowed in each component of the query. Example queries:

:: matches ANY device.
Adafruit:: matches any device whose vendor contains the string “Adafruit”
:Feather: matches any device whose model contains the string “Feather”
Adafruit:Feather: matches any device whose vendor contains the string “Adafruit” AND whose model contains the string “Feather”

device: The same as the above query, except that a device parameter is only allowed to match a single connected device, rather than any number.

board_id

A string specifying Adafruit’s identifier for a CircuitPython-supported board. This corresponds to the lowercase board names found in the URLs of the boards on the CircuitPython Downloads page. For example, a board_id value of raspberry_pi_pico corresponds to the Raspberry Pi Pico board.

A full list of possible values can be seen using the uf2 versions command.

Commands

Syntax

circuitpython-tool [OPTIONS] COMMAND

Description

Tool for interfacing with CircuitPython devices.

Arguments

COMMAND

Valid values:

completion
devices
upload
clean

connect
mount
unmount
uf2

Options

--log-level log_level

Optional. Only display logs at or above ths level.

Aliases:: -l
Environment Variable:: LOG_LEVEL
Choices:: DEBUG, INFO, WARNING, ERROR
Default:: INFO

--fake-device-config fake_device_config

Optional. Path to TOML configuration file for fake devices. For use in tests and demos.

Aliases:: -f
Environment Variable:: FAKE_DEVICE_CONFIG
Type:: file

--version

Optional. Show the version and exit.

Aliases:: -v
Default:: False

completion

Syntax

circuitpython-tool completion

Description

Output shell commands needed for auto-completion.

Evaluating the output of this command will allow auto-completion of this program’s arguments. This can be done as a one-off using:

eval "$(circuitpython-tool completion)"

or by putting the following line in your shell config file (e.g. ~/.bashrc):

source "$(circuitpython-tool completion)"

devices

Syntax

circuitpython-tool devices [OPTIONS] [QUERY]

Description

List all connected CircuitPython devices.

If QUERY is specified, only devices matching that query are listed.

Linux-only.

Arguments

QUERY

Required:: False
Type:: query

Options

--save fake_device_save_path

Optional. If set, save devices to a TOML file for later recall using the --fake-devices flag.

Aliases:: -s
Type:: file

upload

Syntax

circuitpython-tool upload [OPTIONS] DEVICE

Description

Continuously upload code to device in response to source file changes.

The contents of the specified source directory will be copied onto the given CircuitPython device.

If --mode is single-shot, then the code is uploaded and then the command exits.

If --mode is watch, then this commnd will perform one upload, and then will continue running. The command will wait for filesystem events from all paths and descendant paths of the source tree, and will re-upload code to the device on each event.

Linux-only.

Arguments

DEVICE

Required:: True
Type:: device

Options

--dir source_dir

Optional. Path containing source code to upload. If not specified, the source directory is guessed by searching the current directory and its descendants for user code (e.g. code.py).

Aliases:: -d
Type:: directory

--circup, --no-circup

Optional. If True, use circup to automatically install library dependencies on the target device.

Default:: False

--mode mode

Optional. Whether to upload code once, or continuously.

Choices:: single-shot, watch
Default:: watch

--batch-period batch_period

Optional. Batch filesystem events that happen within this period. This reduces spurious uploads when files update in quick succession. Unit: seconds

Type:: float
Default:: 0.25

clean

Syntax

circuitpython-tool clean DEVICE

Description

Deletes all files on the target device, and creates an empty boot.py and code.py on it.

Linux-only.

Arguments

DEVICE

Required:: True
Type:: device

connect

Syntax

circuitpython-tool connect DEVICE

Description

Connect to a device’s serial terminal.

Linux-only.

Arguments

DEVICE

Required:: True
Type:: device

mount

Syntax

circuitpython-tool mount DEVICE

Description

Mounts the specified device if needed, and prints the mountpoint.

Linux-only.

Arguments

DEVICE

Required:: True
Type:: device

unmount

Syntax

circuitpython-tool unmount DEVICE

Description

Unmounts the specified device if needed.

Linux-only.

Arguments

DEVICE

Required:: True
Type:: device

uf2

Syntax

circuitpython-tool uf2 COMMAND

Description

Search and download CircuitPython UF2 binaries.

Arguments

COMMAND

Valid values:

versions
download
devices
install
enter
exit

boot-info
mount
unmount
nuke
analyze

uf2 versions

Syntax

circuitpython-tool uf2 versions

Description

List available CircuitPython boards.

uf2 download

Syntax

circuitpython-tool uf2 download [OPTIONS] BOARD [DESTINATION]

Description

Download CircuitPython image for the requested board.

If DESTINATION is not provided, the file is downloaded to the current directory.

If DESTINATION is a directory, the filename is automatically generated.

Arguments

BOARD

Required:: True
Type:: board_id

DESTINATION

Required:: False
Type:: path

Options

--locale locale

Optional. Locale for CircuitPython install.

Type:: locale
Default:: en_US

--offline, --no-offline

Optional. If True, just print the download URL without actually downloading.

Default:: False

uf2 devices

Syntax

circuitpython-tool uf2 devices

Description

List connected devices that are in UF2 bootloader mode.

Linux-only.

uf2 install

Syntax

circuitpython-tool uf2 install [OPTIONS]

Description

Install a UF2 image onto a connected UF2 bootloader device.

If a CircuitPython device is specified with --device, then we restart that device into its UF2 bootloader and install the image onto it. If --device is not specified, we assume there is already a connected UF2 bootloader device.

Options

--image_path image_path

Optional. If specified, install this already-existing UF2 image.

Aliases:: -i
Type:: file

--board board

Optional. If specified, automatically download and install appropriate CircuitPython UF2 image for this board ID.

Aliases:: -b
Type:: board_id

--device query

Optional. If specified, this device will be restarted into its UF2 bootloader and be used as the target device for installing the image.

Aliases:: -d
Type:: query

--locale locale

Optional. Locale for CircuitPython install. Not used if an explicit image is given using --image_path.

Type:: locale
Default:: en_US

--delete-download, --no-delete-download

Optional. Delete any downloaded UF2 images on exit.

Default:: True

uf2 enter

Syntax

circuitpython-tool uf2 enter DEVICE

Description

Restart selected device into UF2 bootloader.

Linux-only.

Arguments

DEVICE

Required:: True
Type:: device

uf2 exit

Syntax

circuitpython-tool uf2 exit

Description

Restart given UF2 bootloader device into normal application code.

Linux-only.

uf2 boot-info

Syntax

circuitpython-tool uf2 boot-info DEVICE

Description

Lookup UF2 bootloader info of the specified CircuitPython device.

Linux-only.

Arguments

DEVICE

Required:: True
Type:: device

uf2 mount

Syntax

circuitpython-tool uf2 mount

Description

Mount connected UF2 bootloader device if needed and print the mountpoint.

Linux-only.

uf2 unmount

Syntax

circuitpython-tool uf2 unmount

Description

Unmount connected UF2 bootloader device if needed.

Linux-only.

uf2 nuke

Syntax

circuitpython-tool uf2 nuke

Description

Clear out flash memory on UF2 bootloader device.

Linux-only.

uf2 analyze

Syntax

circuitpython-tool uf2 analyze IMAGE_PATH

Description

Print details of each block in a UF2 image.

If run in an interactive terminal, you can use arrow keys to browse blocks. If not run in an interactive context, the information about every block is printed.

Arguments

IMAGE_PATH

Required:: True
Type:: file