Installation

The Memfault CLI tool is a command-line program for integrating Memfault with other systems, such as continuous integration servers.

The tool acts as a client to Memfault's HTTP API.

The Memfault CLI tool is written in Python and published in the Python Package Index (pypi).

Installing the Memfault CLI tool

Install a recent version of Python 3.x.

tip

Use a virtualenv to avoid conflicts with dependencies of other projects that use Python.

Then run pip3 install memfault-cli to install it.

Once installed, the memfault command should be available in your shell:

$ memfault --help
Usage:  [OPTIONS] COMMAND [ARGS]...

Options:
  --email TEXT        Account email to authenticate with
  --password TEXT     Account password or user API key to authenticate with
  --project-key TEXT  Memfault Project Key
  --org-token TEXT    Organization Auth Token
  --org TEXT          Organization slug
  --project TEXT      Project slug
  --verbose           Log verbosely
  --version           Show the version and exit.
  --help              Show this message and exit.

Commands:
  completion                    Generate shell completion script for memfault.
  console                       Open a serial terminal and automatically post chunks to Memfault The command requires output produced by memfault_data_export_chunk.
  deploy-release                Publish a Release to a Cohort.
  post-chunk                    Sends data generated by the memfault-firmware-sdk ("chunks") to the Memfault cloud.
  upload-android-app-symbols    Upload symbols & R8/ProGuard mapping for an Android app build.
  upload-aosp-symbols           Upload symbols for an Android OS/AOSP build.
  upload-bugreport              Upload an Android Bug Report for analysis by Memfault.
  upload-coredump               Upload an MCU coredump for analysis.
  upload-custom-data-recording  Upload a custom data recording (read: any file that might help you with debugging).
  upload-elf-coredump           Upload a Linux ELF coredump for analysis by Memfault.
  upload-elf-symbols            Upload symbols from a tarball of binaries
  upload-mar                    Upload a Memfault Archive File (mar) file for analysis.
  upload-mcu-symbols            Upload symbols for an MCU build.
  upload-ota-payload            Upload a binary to be used for an OTA update.
  upload-software-version-sbom  Upload an SBOM (Software Bill of Materials) in JSON, XML, or YAML format.
  upload-symbols                [DEPRECATED] Upload symbols for an MCU or Android build.
  upload-xed                    Upload an .xed or .xcd file for analysis.
  upload-yocto-symbols          Upload symbols for a Linux Yocto build.

Authentication

Four authentication methods are available for the Memfault CLI:

An Organization Auth Token
A user email and password
A user email and user API key
A Memfault project key

Not all commands work with every authentication method. The following table shows which authentication forms each command requires.

Command	Organization Token	Email + Password	Email + API key	Project Key
deploy-release	✅	✅	✅
post-chunk				✅
upload-android-app-symbols	✅	✅	✅
upload-aosp-symbols	✅	✅	✅
upload-bugreport	✅	✅	✅	✅
upload-coredump	✅	✅	✅	✅
upload-custom-data-recording	✅	✅	✅	✅
upload-elf-coredump	✅	✅	✅	✅
upload-elf-symbols	✅	✅	✅
upload-mar	✅	✅	✅	✅
upload-mcu-symbols	✅	✅	✅
upload-ota-payload	✅	✅	✅
upload-xed	✅	✅	✅	✅
upload-yocto-symbols	✅	✅	✅
console				✅

Using an Organization Auth Token

To use an Organization Auth Token, pass --org-token with the contents of your Organization Auth Token after the memfault command.

memfault --org-token ${ORGANIZATION_AUTH_TOKEN} ...

Using email and password or user API key

To use email and password authentication, pass --email and --password after the memfault command.

memfault --email ${YOUR_EMAIL} --password ${USER_PASSWORD} ...

memfault --email ${YOUR_EMAIL} --password ${YOUR_USER_API_KEY} ...

Using a project key

To use a Memfault project key, pass --project-key after the memfault command.

memfault --project-key ${YOUR_PROJECT_KEY} ...

Example usage: uploading MCU symbols

note

This operation requires an Organization Auth Token or User API Key.

Build ID
Software Version

For devices that use Build IDs, upload MCU symbols like this:

memfault \
  --org-token ${ORGANIZATION_AUTH_TOKEN} \
  --org acme-inc \
  --project smart-sink \
   upload-mcu-symbols \
   build/zephyr/zephyr.elf

For devices that use software version as the unique identifier for symbol files, pass additional arguments when uploading:

memfault \
  --org-token ${ORGANIZATION_AUTH_TOKEN} \
  --org acme-inc \
  --project smart-sink \
   upload-mcu-symbols \
   --software-type stm32-fw \
   --software-version 1.0.0-alpha \
   build/stm32-fw.elf

Tip

If you work with the same project regularly, add standard arguments as environment variables in your shell init file or on the command line:

$ export MEMFAULT_ORG_TOKEN=<Organization Token>
$ export MEMFAULT_ORG=<Organization slug>
$ export MEMFAULT_PROJECT=<Project slug>

The invocation then reduces to:

memfault upload-mcu-symbols \
  --hardware-version mp \
  --software-type stm32-fw \
  --software-version 1.0.0-alpha \
  build/stm32-fw.elf

INFO: build/stm32-fw.elf: uploaded!
INFO: You can view in the UI here:
    <Link to Symbols in UI>

Installing the Memfault CLI tool​

Authentication​

Using an Organization Auth Token​

Using email and password or user API key​

Using a project key​

Example usage: uploading MCU symbols​