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
| Argument | Required | Description |
|---|---|---|
elf_path | Yes* | Path to the ELF file (*not required with --identical) |
ld_scripts | No | Space-separated linker script paths in quotes (if omitted, uses default Code/Data regions based on ELF section flags). See supported formats. |
Mode Options
| Option | Description |
|---|---|
--upload | Upload report to MemBrowse platform |
--no-git | Disable auto-detection of Git metadata when uploading |
--github | Use GitHub Actions environment for Git metadata detection (use with --upload) |
Upload Options
Required when using --upload:
| Option | Description |
|---|---|
--api-key KEY | MemBrowse API key |
--target-name NAME | Build configuration/target (e.g., esp32, stm32, x86) |
--api-url URL | MemBrowse API base URL (default: https://api.membrowse.com) |
--identical | Mark 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:
| Option | Description |
|---|---|
--commit-sha | Git commit SHA |
--parent-sha | Git parent commit SHA. Use append to set the parent to the head of the default branch, or none for no parent. |
--base-sha | Alias for --parent-sha |
--branch-name | Git branch name |
--repo-name | Repository name |
--default-branch | Repository default branch |
--commit-message | Commit message |
--commit-timestamp | Commit timestamp (ISO format) |
--author-name | Commit author name |
--author-email | Commit author email |
--tags | Git tag name(s), space-separated |
--pr-number | Pull request number |
--pr-name | Pull request name/title |
--pr-author-name | Pull request author name |
--pr-author-email | Pull request author email |
Analysis Options
| Option | Description |
|---|---|
--skip-line-program | Skip DWARF line program processing for faster analysis |
--def VAR=VALUE | Define linker script variable (can be specified multiple times) |
--ld-include-dir DIR | Directory searched for linker script INCLUDE files: the linker's -L directories (can be specified multiple times) |
--map-file PATH | Linker map file for archive and object file attribution (GNU LD, LLD or IAR) |
--limits PATH | Linker 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-alignment | Don'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 NAME | Exclude an ELF section by exact name, along with its symbols (can be specified multiple times) |
--source-root DIR | Directory 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), includingINCLUDEd 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
| Option | Description |
|---|---|
--dont-fail-on-alerts | Exit 0 even if budget alerts triggered |
Output Options
| Option | Description |
|---|---|
--json | Output report as JSON (default is human-readable format) |
--all-symbols | Display all symbols instead of just top 20 (human-readable mode only) |
--output-raw-response | Output 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:
| Field | Description |
|---|---|
comparison_url | Link to the build comparison in the portal |
target_name | The target name |
pr_number | The pull request number, if any |
api_response.success | Whether the upload succeeded |
api_response.data.changes | Memory differences compared to the base commit, broken down by regions, sections, files and symbols |
api_response.data.alerts | Budget alerts triggered, under budgets |
api_response.data.is_overwritten | Whether 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
| Argument | Required | Description |
|---|---|---|
commit_sha | Yes | Git commit SHA to retrieve summary for |
Options
| Option | Description |
|---|---|
--api-key KEY | MemBrowse API key (required) |
--api-url URL | MemBrowse API base URL (default: https://api.membrowse.com) |
--json | Output raw JSON response from API (includes targets array with per-target summaries) |
--template PATH | Path 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.
| Variable | Description |
|---|---|
targets | List of targets (see below) |
has_alerts | true if any target has budget alerts |
file_changes | One row per changed source file across all targets (see below) |
targets_with_file_changes | How many targets have per-file changes |
dashboard_url | The project's dashboard at this commit. Only set when the data comes from the summary API. |
Each item in targets has:
| Field | Description |
|---|---|
name | Target name |
comparison_url | Link to this target's comparison in the portal |
regions | Changed regions, with name, used_size, limit_size, delta, delta_str, delta_pct_str and utilization_pct |
sections | Changed sections, with name, region, size, delta and delta_str |
sections_by_region | The same sections, grouped by region name |
files | Per-file changes, one entry per file and region, with name, region, kind (flash, ram or other), size, old_size, delta and delta_str |
symbols | added, removed, modified and moved symbols. Only filled in the comment-action's file mode, and empty when the data comes from the summary API. |
alerts | Budget alerts, with budget_name, region, usage, limit and exceeded |
has_changes, has_alerts, has_file_changes | Whether 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
| Argument | Required | Description |
|---|---|---|
num_commits | No | Number of commits to process (required unless --commits is used) |
build_script | Yes | Shell command to build the firmware (quoted) |
elf_path | Yes | Path to ELF file after build |
target_name | Yes | Target name in MemBrowse |
api_key | Yes | MemBrowse API key |
api_url | No | MemBrowse API base URL (default: https://api.membrowse.com). When using --commits, use --api-url instead. |
Options
| Option | Description |
|---|---|
--api-url URL | MemBrowse API base URL, as an alternative to the positional api_url. Required for a custom URL when using --commits. |
--ld-scripts SCRIPTS | Space-separated linker script paths (if omitted, uses default Code/Data regions). See supported formats. |
--def VAR=VALUE | Define linker script variable (can be specified multiple times) |
--ld-include-dir DIR | Directory searched for linker script INCLUDE files (can be specified multiple times) |
--map-file PATH | Linker map file for archive and object file attribution |
--limits PATH | Linker script with the real LENGTH of each region. Applied to every commit built. |
--exclude-alignment | Don't count explicit ALIGN padding as used memory. Applied to every commit built; commits uploaded earlier without it keep the padding counted. |
--skip-section NAME | Exclude an ELF section by exact name (can be specified multiple times). Applied to every commit built. |
--source-root DIR | Directory 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 HASH | Start processing from this commit hash (must be on the main branch). Only valid with num_commits. |
--commits REFS | Space-separated list of commit hashes and/or tags to process. Mutually exclusive with num_commits, --initial-commit and --binary-search. |
--initial-parent REF | Set the parent of the first commit when using --commits. Used to chain multiple onboard runs together. Only valid with --commits. |
--binary-search | Minimize 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-run | Run 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
- 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.
- Uses
--first-parentto follow only main branch (not feature branch commits) - Iterates from oldest to newest commit
- 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
- Skips building commits with no changes in
--build-dirs(uploads metadata-only) - With
--binary-search, builds only endpoints first, then bisects where memory fingerprints differ - Uploads empty reports for failed builds and continues with the next commit
- Restores original HEAD when complete
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:
| Option | Description |
|---|---|
-v, --verbose LEVEL | Set logging verbosity: INFO (default), WARNING, DEBUG |
--help | Show 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
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Error (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.)