8  Chapter 7: Using bl4 Tools

Everything we’ve learned—binary decoding, memory analysis, save file encryption, serial parsing—comes together in the bl4 command-line tools. This chapter serves as your practical reference for day-to-day use.

The tools are designed to be composable. Pipe output between commands. Chain operations together. Build your own workflows for tasks we haven’t anticipated.

8.1 Building the Tools

8.1.1 Prerequisites

# Install Rust (if you haven't already)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

# Clone the repository
git clone https://github.com/monokrome/bl4
cd bl4

8.1.2 Build

cargo build --release -p bl4-cli

# Binary appears in ./target/release/bl4

8.2 CLI Structure

The bl4 CLI uses subcommands organized by function:

bl4 <COMMAND>

Commands:
  save       Save file operations (decrypt, encrypt, edit, get, set)
  inspect    Inspect a save file (decrypt and display info)
  configure  Configure default settings
  serial     Item serial operations (decode, encode, compare, modify)
  parts      Query parts database
  memory     Read/analyze game memory (live process or dump file)
  idb        Manage the verified items database
  launch     Launch Borderlands 4 with instrumentation

Aliases exist for common commands: s (save), i (inspect), r (serial), m (memory), p (parts).

8.3 Save File Operations

8.3.1 Inspect a Save

Quick view of save contents:

bl4 inspect 1.sav
bl4 inspect 1.sav --full  # Show complete YAML

8.3.2 Decrypt/Encrypt

# Decrypt to stdout
bl4 save decrypt 1.sav

# Decrypt to file
bl4 save decrypt 1.sav character.yaml

# Encrypt back
bl4 save encrypt character.yaml 1.sav

Steam ID is auto-detected from configuration or can be specified:

bl4 save decrypt 1.sav --steam-id 76561198012345678

8.3.3 Edit Interactively

Opens decrypted save in your $EDITOR, then re-encrypts on save:

bl4 save edit 1.sav

8.3.4 Get/Set Values

Query specific paths:

bl4 save get 1.sav "state.currencies.cash"
bl4 save get 1.sav --level   # Character level
bl4 save get 1.sav --money   # Currencies
bl4 save get 1.sav --all     # Everything

Set values:

bl4 save set 1.sav "state.currencies.cash" 999999999

8.4 Serial Operations

8.4.1 Decode

bl4 serial decode '@Ugr$ZCm/&tH!t{KgK/Shxu>k'

Output:

Serial: @Ugr$ZCm/&tH!t{KgK/Shxu>k
Item type: r (Item)
Category: Vladof SMG (22)
Level: 50
Tokens: 180928 | 50 | {0:1} 21 {4} , 2 , , 105 102 41

Options:

bl4 serial decode --verbose '@Ugr...'  # Byte breakdown
bl4 serial decode --debug '@Ugr...'    # Bit-by-bit parsing
bl4 serial decode --analyze '@Ugr...'  # Token analysis

8.4.2 Compare

Side-by-side comparison of two serials:

bl4 serial compare '@Ugr$ZCm...' '@Ugr$ABC...'

8.4.3 Modify

Swap parts between serials:

bl4 serial modify '@base...' '@source...' '4,12'

8.4.4 Batch Decode

Decode many serials to binary for analysis:

bl4 serial batch-decode serials.txt serials.bin

8.5 Items Database (idb)

The items database tracks verified item data with source attribution.

8.5.1 Basic Operations

bl4 idb init                    # Create database
bl4 idb stats                   # Show counts
bl4 idb list                    # List all items
bl4 idb show '@Ugr...'          # Show item details

8.5.2 Import Items

# From save file
bl4 idb import-save 1.sav --decode --legal --source monokrome

# Decode all and populate metadata
bl4 idb decode-all

8.5.3 Attachments

bl4 idb attach '@Ugr...' screenshot.png

8.5.4 Value Attribution

Track values from different sources:

bl4 idb set-value '@Ugr...' rarity Epic --source ingame --confidence verified
bl4 idb get-values '@Ugr...' rarity

8.6 Memory Operations

Memory commands work with live processes or dump files.

8.6.1 With Dump File

bl4 memory --dump game.dmp info
bl4 memory --dump game.dmp discover gnames
bl4 memory --dump game.dmp discover guobjectarray

8.6.2 Generate Usmap

bl4 memory --dump game.dmp dump-usmap

8.6.3 FName Operations

bl4 memory --dump game.dmp fname 12345
bl4 memory --dump game.dmp fname-search "Damage"

8.6.4 Parts Extraction

bl4 memory --dump game.dmp dump-parts -o parts.json
bl4 memory --dump game.dmp build-parts-db -i parts.json -o parts_db.json

8.7 Configuration

Set defaults to avoid repetition:

bl4 configure --steam-id 76561198012345678
bl4 configure --show

Environment variable BL4_ITEMS_DB sets the default items database path.

8.8 Common Workflows

8.8.1 Edit a Save

bl4 save edit ~/.steam/.../1.sav
# Editor opens, make changes, save & quit
# File is automatically re-encrypted

8.8.2 Analyze an Item

# Extract serial from save
bl4 save get 1.sav "state.inventory.items[0].serial"

# Decode it
bl4 serial decode '@Ugr...'

# Look up in database
bl4 idb show '@Ugr...'

8.8.3 Import Items from Saves

for sav in saves/*.sav; do
  bl4 idb import-save "$sav" --decode --legal
done
bl4 idb stats

8.8.4 Update After Game Patch

# New memory dump
sudo gcore -o bl4_new $(pgrep -f wine64-preloader)

# Generate new usmap
bl4 memory --dump bl4_new.* dump-usmap

# Re-extract parts
bl4 memory --dump bl4_new.* extract-parts -o share/manifest/

8.9 Shell Tips

8.9.1 Quoting Serials

Serials contain $, !, @. Always use single quotes:

bl4 serial decode '@Ugr$ZCm/&tH!t{KgK/Shxu>k'

8.9.2 Aliases

alias bl4d='bl4 serial decode'
alias bl4i='bl4 inspect'
alias bl4e='bl4 save edit'

8.9.3 Piping

bl4 serial decode '@Ugr...' | grep "Category"
bl4 idb list | wc -l

8.10 Troubleshooting

8.10.1 “Decryption failed”

  • Wrong Steam ID
  • Corrupted save file
  • Not a BL4 save

Verify the Steam ID matches the save file path.

8.10.2 “Invalid serial”

  • Missing @Ug prefix
  • Truncated copy
  • Wrong quote type in shell

Copy the complete serial and use single quotes.

8.10.3 “Memory read failed”

  • Address outside dump range
  • Corrupted dump

Verify the dump covers the target address.

8.11 Quick Reference

Command Description
bl4 inspect <FILE> Quick save inspection
bl4 save decrypt <IN> [OUT] Decrypt save to YAML
bl4 save encrypt <IN> <OUT> Encrypt YAML to save
bl4 save edit <FILE> Edit in $EDITOR
bl4 save get <FILE> <PATH> Query value
bl4 save set <FILE> <PATH> <VAL> Set value
bl4 serial decode <SERIAL> Decode item serial
bl4 serial compare <S1> <S2> Compare serials
bl4 idb stats Database statistics
bl4 idb import-save <FILE> Import from save
bl4 memory --dump <F> <CMD> Memory analysis

8.12 What’s Next?

The appendices provide deep reference material: