Memfault CLI tool

The Memfault CLI tool is a simple command-line program which purpose is to make integrations with the Memfault cloud from other systems, like continuous integration servers, as easy as possible.

Under the hood, the tool acts as a client to Memfault's HTTP API.

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

Installing the Memfault CLI tool

To install it, make sure you have a recent version of Python 3.x installed.

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: memfault [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-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

There are four different ways to authenticate using the Memfault CLI.

With an Organization Auth token
With a user email and password
With a user email and user API key
With a Memfault Project key

Not all commands will work with every authentication method. Below shows which commands require which forms of authentication.

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 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 Memfault 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 are using Build IDs, uploading MCU symbols is done like so:

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

For devices that are using Software Version as the unique identifier for Symbol Files, additional arguments must be passed 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 are going to be working with the same project you can add standard arguments as environment variables to your shell init file or via the command line:

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

With these changes, the invocation 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 Organization Auth Token​

Using Email and Password or User API Key​

Using Memfault Project Key​

Example Usage: Uploading MCU Symbols​