Skip to main content

CLI Reference

Complete reference for the membrowse command-line tool. For the GitHub Actions integration, see the membrowse-action repository.

Installation​

pip install membrowse

To update to the latest version:

pip install --upgrade membrowse

Requirements: Python 3.9+

To check the installed version, run pip show membrowse.

Quick Start​

# Generate a local report
membrowse report build/firmware.elf "linker.ld"

# Output as JSON (for troubleshooting)
membrowse report build/firmware.elf "linker.ld" --json

# Analyze and upload to MemBrowse
membrowse report build/firmware.elf "linker.ld" \
--upload \
--target-name my-target \
--api-key YOUR_API_KEY

Commands​

membrowse report​

Generate and optionally upload a memory report.

membrowse report <elf_path> [ld_scripts] [options]

Arguments​

ArgumentRequiredDescription
elf_pathYes*Path to the ELF file (*not required with --identical)
ld_scriptsNoSpace-separated linker script paths in quotes (if omitted, uses default Code/Data regions based on ELF section flags). See supported formats.

Mode Options​

OptionDescription
--uploadUpload report to MemBrowse platform
--no-gitDisable auto-detection of Git metadata when uploading
--githubUse GitHub Actions environment for Git metadata detection (use with --upload)

Upload Options​

Required when using --upload:

OptionDescription
--api-key KEYMemBrowse API key
--target-name NAMEBuild configuration/target (e.g., esp32, stm32, x86)
--api-url URLMemBrowse API base URL (default: https://api.membrowse.com)
--identicalMark commit as having identical memory footprint to previous (metadata-only upload, no ELF analysis required)

Git Metadata Options​

These are auto-detected by default. Use --no-git to disable auto-detection, or specify manually to override:

OptionDescription
--commit-shaGit commit SHA
--parent-shaGit parent commit SHA. Use append to set the parent to the head of the default branch, or none for no parent.
--base-shaAlias for --parent-sha
--branch-nameGit branch name
--repo-nameRepository name
--default-branchRepository default branch
--commit-messageCommit message
--commit-timestampCommit timestamp (ISO format)
--author-nameCommit author name
--author-emailCommit author email
--tagsGit tag name(s), space-separated
--pr-numberPull request number
--pr-namePull request name/title
--pr-author-namePull request author name
--pr-author-emailPull request author email

Analysis Options​

OptionDescription
--skip-line-programSkip DWARF line program processing for faster analysis
--def VAR=VALUEDefine linker script variable (can be specified multiple times)
--ld-include-dir DIRDirectory searched for linker script INCLUDE files: the linker's -L directories (can be specified multiple times)
--map-file PATHLinker map file for archive and object file attribution (GNU LD, LLD or IAR)
--limits PATHLinker script with the real LENGTH of each region, for builds linked with inflated region sizes. Sections are still assigned using ld_scripts; utilization and overflow use these sizes. Requires ld_scripts, and regions must have the same ORIGIN in both.
--exclude-alignmentDon't count padding from explicit . = ALIGN(n) statements as used memory. Exact with a GNU LD or LLD map file, otherwise estimated from ELF symbols. Lowers the reported usage from that commit onward.
--skip-section NAMEExclude an ELF section by exact name, along with its symbols (can be specified multiple times)
--source-root DIRDirectory that source files are reported relative to (e.g., src/drivers/uart.c instead of uart.c). Files outside it, or all files when not set, are reported by basename. The first upload after turning this on shows in-repo symbols as moved.

These options are described in more detail under Analysis Options in the GitHub Actions guide.

Supported Linker Script Formats​

  • GNU LD linker scripts (.ld, .cmd), including INCLUDEd files
  • IAR ICF files (.icf)
  • Keil/Arm scatter files (.sct)
  • SEGGER Embedded Studio project files (.emProject)

The format is detected from the file's content, so the extension doesn't have to match.

Alert Options​

OptionDescription
--dont-fail-on-alertsExit 0 even if budget alerts triggered

Output Options​

OptionDescription
--jsonOutput report as JSON (default is human-readable format)
--all-symbolsDisplay all symbols instead of just top 20 (human-readable mode only)
--output-raw-responseOutput raw API response as JSON to stdout

Upload Response​

Use --output-raw-response to write the upload result to stdout as JSON for further processing. It has this structure:

FieldDescription
comparison_urlLink to the build comparison in the portal
target_nameThe target name
pr_numberThe pull request number, if any
api_response.successWhether the upload succeeded
api_response.data.changesMemory differences compared to the base commit, broken down by regions, sections, files and symbols
api_response.data.alertsBudget alerts triggered, under budgets
api_response.data.is_overwrittenWhether this upload replaced an existing report

If the upload fails, nothing is written to stdout and the command exits with code 1.

RESULT=$(membrowse report \
build/firmware.elf \
"linker.ld" \
--upload \
--target-name my-target \
--api-key YOUR_API_KEY \
--output-raw-response)

echo "$RESULT" | jq '.api_response.data.changes'

Examples​

# Local analysis - human-readable output (default)
membrowse report build/firmware.elf "linker.ld"

# Local analysis without linker scripts (uses default Code/Data regions)
membrowse report build/firmware.elf

# Show all symbols locally
membrowse report build/firmware.elf "linker.ld" --all-symbols

# Output as JSON
membrowse report build/firmware.elf "linker.ld" --json

# Upload to MemBrowse (Git metadata auto-detected)
membrowse report build/firmware.elf "linker.ld" \
--upload \
--target-name my-target \
--api-key YOUR_API_KEY

# Upload without Git metadata
membrowse report build/firmware.elf "linker.ld" \
--upload --no-git \
--target-name my-target \
--api-key YOUR_API_KEY

# GitHub Actions mode (auto-detects Git metadata from GitHub environment)
membrowse report build/firmware.elf "linker.ld" \
--upload --github \
--target-name stm32f4 \
--api-key YOUR_API_KEY

# Multiple linker scripts
membrowse report build/firmware.elf "memory.ld sections.ld" \
--upload \
--target-name my-target \
--api-key YOUR_API_KEY

# Define linker script variables
membrowse report build/firmware.elf "linker.ld" \
--def __flash_size__=4096K \
--def __ram_size__=256K

# Attribute symbols to archives and report repository-relative source paths
membrowse report build/firmware.elf "linker.ld" \
--map-file build/firmware.map \
--source-root .

# Report usage against the real limits of a build linked with inflated regions
membrowse report build/firmware.elf "build/inflated.ld" \
--limits boards/my-board/real-memory.ld

membrowse summary​

Retrieve memory footprint summaries for a commit from the MemBrowse API. Returns data for all targets associated with the commit — each target's region changes, section changes, per-source-file changes, and layout are included in the response under a targets list.

Per-file changes (changes.files) sum each target's symbols by source file and region and list the files whose total differs from the base commit's, so a template can report which files grew or shrank, and by how much, without symbol-level data.

membrowse summary <commit_sha> --api-key KEY [options]

Arguments​

ArgumentRequiredDescription
commit_shaYesGit commit SHA to retrieve summary for

Options​

OptionDescription
--api-key KEYMemBrowse API key (required)
--api-url URLMemBrowse API base URL (default: https://api.membrowse.com)
--jsonOutput raw JSON response from API (includes targets array with per-target summaries)
--template PATHPath to custom Jinja2 template file (default: built-in template). See Template Variables.

--json and --template are mutually exclusive.

Examples​

# Human-readable summary (all targets)
membrowse summary abc123def --api-key YOUR_API_KEY

# Raw JSON output (for scripting)
membrowse summary abc123def --api-key YOUR_API_KEY --json

# Custom template
membrowse summary abc123def --api-key YOUR_API_KEY --template my_template.j2

Template Variables​

Custom templates, used by --template and by the comment-action's comment_template input, receive these variables. See the default template for an example.

VariableDescription
targetsList of targets (see below)
has_alertstrue if any target has budget alerts
file_changesOne row per changed source file across all targets (see below)
targets_with_file_changesHow many targets have per-file changes
dashboard_urlThe project's dashboard at this commit. Only set when the data comes from the summary API.

Each item in targets has:

FieldDescription
nameTarget name
comparison_urlLink to this target's comparison in the portal
regionsChanged regions, with name, used_size, limit_size, delta, delta_str, delta_pct_str and utilization_pct
sectionsChanged sections, with name, region, size, delta and delta_str
sections_by_regionThe same sections, grouped by region name
filesPer-file changes, one entry per file and region, with name, region, kind (flash, ram or other), size, old_size, delta and delta_str
symbolsadded, removed, modified and moved symbols. Only filled in the comment-action's file mode, and empty when the data comes from the summary API.
alertsBudget alerts, with budget_name, region, usage, limit and exceeded
has_changes, has_alerts, has_file_changesWhether the target has region changes, budget alerts or per-file changes

Each row in file_changes has name, builds (how many targets the file changed in) and a flash, ram and other entry. Each of those entries gives the file's smallest and largest delta across targets as min, max, min_str, max_str, min_build, max_build and builds. Rows are sorted by their largest absolute delta.

The comment-action adds the comment header and footer around your template's output.


membrowse onboard​

Analyze historical commits to build baseline data. Supports two modes: processing the last N commits, or processing a specific list of commits/tags.

# Mode 1: Last N commits
membrowse onboard <num_commits> <build_script> <elf_path> <target_name> <api_key> [api_url] [options]

# Mode 2: Specific commits
membrowse onboard <build_script> <elf_path> <target_name> <api_key> --commits "REF1 REF2 ..." [options]

Arguments​

ArgumentRequiredDescription
num_commitsNoNumber of commits to process (required unless --commits is used)
build_scriptYesShell command to build the firmware (quoted)
elf_pathYesPath to ELF file after build
target_nameYesTarget name in MemBrowse
api_keyYesMemBrowse API key
api_urlNoMemBrowse API base URL (default: https://api.membrowse.com). When using --commits, use --api-url instead.

Options​

OptionDescription
--api-url URLMemBrowse API base URL, as an alternative to the positional api_url. Required for a custom URL when using --commits.
--ld-scripts SCRIPTSSpace-separated linker script paths (if omitted, uses default Code/Data regions). See supported formats.
--def VAR=VALUEDefine linker script variable (can be specified multiple times)
--ld-include-dir DIRDirectory searched for linker script INCLUDE files (can be specified multiple times)
--map-file PATHLinker map file for archive and object file attribution
--limits PATHLinker script with the real LENGTH of each region. Applied to every commit built.
--exclude-alignmentDon't count explicit ALIGN padding as used memory. Applied to every commit built; commits uploaded earlier without it keep the padding counted.
--skip-section NAMEExclude an ELF section by exact name (can be specified multiple times). Applied to every commit built.
--source-root DIRDirectory that source files are reported relative to
--build-dirs DIR [DIR ...]Directories that trigger rebuilds. Commits with no changes in these directories upload metadata-only reports with identical=True. Mutually exclusive with --binary-search, and ignored when using --commits.
--initial-commit HASHStart processing from this commit hash (must be on the main branch). Only valid with num_commits.
--commits REFSSpace-separated list of commit hashes and/or tags to process. Mutually exclusive with num_commits, --initial-commit and --binary-search.
--initial-parent REFSet the parent of the first commit when using --commits. Used to chain multiple onboard runs together. Only valid with --commits.
--binary-searchMinimize builds using binary search — builds endpoints first, compares memory fingerprints, and only builds midpoints where changes are detected. Mutually exclusive with --build-dirs and --commits.
--dry-runRun the full workflow but skip uploading reports (logs what would be uploaded)

Examples​

# Basic onboarding with linker scripts
membrowse onboard \
50 \
"make clean && make all" \
build/firmware.elf \
my-target \
YOUR_API_KEY \
--ld-scripts "linker.ld"

# Without linker scripts (uses default Code/Data regions)
membrowse onboard \
50 \
"make clean && make all" \
build/firmware.elf \
my-target \
YOUR_API_KEY

# With custom API URL
membrowse onboard \
25 \
"idf.py build" \
build/firmware.elf \
esp32 \
YOUR_API_KEY \
https://custom-api.example.com \
--ld-scripts "build/esp-idf/esp32/esp32.project.ld"

# Skip commits without changes in build directories
membrowse onboard \
100 \
"make all" \
build/firmware.elf \
my-target \
YOUR_API_KEY \
--ld-scripts "linker.ld" \
--build-dirs src/ lib/ include/

# Start from a specific commit
membrowse onboard \
50 \
"make all" \
build/firmware.elf \
my-target \
YOUR_API_KEY \
--ld-scripts "linker.ld" \
--initial-commit abc123def

# Onboard specific version tags
membrowse onboard \
"make clean && make all" \
build/firmware.elf \
my-target \
YOUR_API_KEY \
--commits "v1.0 v1.1 v2.0 v2.1" \
--ld-scripts "linker.ld"

# Chain multiple onboard runs across version boundaries
membrowse onboard \
"make clean && make all" \
build/firmware.elf \
my-target \
YOUR_API_KEY \
--commits "v2.0 v2.1 v2.2" \
--initial-parent v1.9 \
--ld-scripts "linker.ld"

# Minimize builds with binary search
membrowse onboard \
100 \
"make all" \
build/firmware.elf \
my-target \
YOUR_API_KEY \
--ld-scripts "linker.ld" \
--binary-search

# Dry run to verify setup without uploading
membrowse onboard \
10 \
"make all" \
build/firmware.elf \
my-target \
YOUR_API_KEY \
--ld-scripts "linker.ld" \
--dry-run

Behavior​

  1. Requires a full clone, and checks the working tree. Outside CI, it refuses to start if tracked files have local changes. In CI, it logs a warning and continues.
  2. Uses --first-parent to follow only main branch (not feature branch commits)
  3. Iterates from oldest to newest commit
  4. For each commit:
    • Force-checks out the commit and force-updates submodules
    • Runs git clean -fdx, including inside submodules
    • Runs the build script
    • Analyzes the ELF file
    • Uploads the report
  5. Skips building commits with no changes in --build-dirs (uploads metadata-only)
  6. With --binary-search, builds only endpoints first, then bisects where memory fingerprints differ
  7. Uploads empty reports for failed builds and continues with the next commit
  8. Restores original HEAD when complete
Untracked files are deleted

git clean -fdx removes all untracked and gitignored files from the checkout, including those in submodules. When running membrowse onboard locally, use a separate clone if you have files you want to keep.

A commit uploaded by onboarding only moves a branch head if MemBrowse can prove it descends from the current head, so onboarding older history doesn't affect a head set by your regular CI.


Global Options​

These options apply to all commands, and go before the subcommand:

OptionDescription
-v, --verbose LEVELSet logging verbosity: INFO (default), WARNING, DEBUG
--helpShow help message
# Warnings and errors only
membrowse -v WARNING report build/firmware.elf "linker.ld"

# Debug output
membrowse -v DEBUG report build/firmware.elf "linker.ld"

Exit Codes​

CodeMeaning
0Success
1Error (budget alert, invalid input, API error, etc.)

Use --dont-fail-on-alerts to prevent budget alerts from causing exit code 1.


Output Formats​

Human-Readable (default)​

ELF Metadata: build/firmware.elf  |  Arch: ARM  |  Machine: EM_ARM  |  Toolchain: gcc-10.3.1  |  Entry: 0x0802015d  |  Type: ET_EXEC
==========================================================================================================================================================

Region Address Range Size Used Free Utilization
--------------------------------------------------------------------------------------------------------------------------------------------
FLASH 0x08000000-0x08100000 1,048,576 bytes 365,192 bytes 683,384 bytes [██████░░░░░░░░░░░░░░] 34.8%
└─ FLASH_START 0x08000000-0x08004000 16,384 bytes 14,708 bytes 1,676 bytes [█████████████████░░░] 89.8%
• .isr_vector 392 bytes
• .isr_extratext 14,316 bytes
└─ FLASH_TEXT 0x08020000-0x08100000 917,504 bytes 350,484 bytes 567,020 bytes [███████░░░░░░░░░░░░░] 38.2%
• .text 350,476 bytes
RAM 0x20000000-0x20020000 131,072 bytes 26,960 bytes 104,112 bytes [████░░░░░░░░░░░░░░░░] 20.6%
• .bss 8,476 bytes
• .heap 16,384 bytes
• .stack 2,048 bytes

Top 20 Largest Symbols
======================

Name Address Size Type Section Source
--------------------------------------------------------------------------------------------------------------------------------------------
usb_device 0x20000a30 5,444 bytes OBJECT .bss usb.c
mp_qstr_const_pool 0x08062b70 4,692 bytes OBJECT .text qstr.c
mp_execute_bytecode 0x080392f9 4,208 bytes FUNC .text vm.c
...

JSON (with --json)​

When using --json, the report is output as JSON to stdout. When uploading with --upload, a JSON report is generated containing:

  • Memory regions with usage
  • All sections with sizes
  • Complete symbol table
  • Git metadata (commit, branch, etc.)