forb
Binary to human, instantly. A CLI tool that automatically detects and converts data between formats.
$ forb 691E01B8
▶ hex (92% confidence)
4 bytes
→ ipv4: 105.30.1.184
→ epoch-seconds: 2025-11-19T17:43:20+00:00
≈ binary: 01101001 00011110 00000001 10111000
≈ base64: aR4BuA==
≈ int-be: 1763574200
… (8 more, use -l 0 to show all)
Conversions are sorted by usefulness - structured data (JSON, MessagePack, Protobuf) first, then semantic types (datetime, UUID, IP), then encodings. Structured data is pretty-printed with syntax highlighting.
graph LR
input(["691E01B8"])
hex["hex (92%)"]
input -->|parse| hex
hex --> ipv4["105.30.1.184"]
hex -->|int-be| epoch["2025-11-19T17:43:20Z"]
hex --> base64["aR4BuA=="]
hex --> binary["01101001..."]
Why forb?
Ever paste a blob of hex into a dozen different tools trying to figure out what it is? forb does it all at once. It tries every interpretation and shows you what makes sense.
- Hex dump from a debugger? See it as integers, timestamps, base64
- Random UUID in logs? Instantly see which version and extract the timestamp
- Timestamp that could be seconds or milliseconds? See both interpretations
- Space-separated hex bytes? Just paste them directly
Installation
Homebrew (macOS/Linux)
Scoop (Windows)
scoop bucket add mjukis https://github.com/mjukis-ab/scoop-bucket
scoop install forb
Cargo (Rust)
Debian/Ubuntu
Download the .deb from GitHub Releases, then:
From Source
# Binary is at target/release/forb
Pre-built Binaries
Download from GitHub Releases.
Usage
Direct Input
# Hex (multiple formats supported)
# Base64
# Timestamps
# UUIDs
# IP addresses
# Coordinates
# Colors
Pipe Mode
Pipe logs through forb to automatically annotate interesting values:
|
[2024-01-15 10:30:45] User 550e8400-e29b-41d4-a716-446655440000 logged in
↳ uuid: UUID v4 (random) → hex: 550E8400E29B41D4A716446655440000
[2024-01-15 10:30:46] Received payload: 69 1E 01 B8
↳ hex: 4 bytes → int-be: 1763574200, epoch: 2025-11-19T17:43:20Z
Pipe Mode Options
# Lower threshold to catch more matches (default: 0.8)
|
# Highlight matched values inline
|
# Only look for specific formats
|
# JSON output for scripting
|
Output Options
# Human-readable (default, shows top 5 conversions)
# Show more/fewer conversions
# Compact output (single-line JSON/protobuf)
# Disable colors (for piping to files)
# JSON for scripting
# Raw output (just values, for scripting)
# Show only highest-confidence interpretation
# Force specific format
# Packet layout for binary formats (protobuf, msgpack)
# List all supported formats
Graph Output
Visualize the conversion graph:
# Graphviz DOT format (pipe to dot to render)
|
# Mermaid format (renders in GitHub/GitLab markdown)
Supported Formats
| Category | Formats |
|---|---|
| Encoding | hex, base64, binary, octal, url-encoding, escape sequences (\x48, \u0048) |
| Hashing | MD5, SHA-1, SHA-256, SHA-512 (detection by length) |
| Numbers | decimal, binary, octal, data sizes (1MB, 1MiB), temperature (30°C, 86°F) |
| Math | Expression evaluation (2 + 2, 0xFF + 1, 1 << 8, 0b1010 | 0b0101, USD(100)) |
| Units | length, weight, volume, speed, pressure, energy, angle, area (with SI prefixes) |
| Currency | 100 USD, $50, 5kEUR, 2.5MSEK (with live exchange rates) |
| Time | Unix epoch (sec/ms), Apple/Cocoa, Windows FILETIME, ISO 8601, durations (1h30m) |
| Identifiers | UUID (v1-v8 detection), ULID (with timestamp), NanoID, CUID2, JWT |
| Network | IPv4, IPv6 |
| Coordinates | Decimal degrees, DMS, DDM, Geohash, Plus Code, UTM, MGRS, SWEREF 99 |
| Colors | #RGB, #RRGGBB, rgb(), rgba(), hsl(), hsla(), 0xAARRGGBB (Android) |
| Data | JSON, MessagePack, Protobuf (schema-less), plist (XML/binary), UTF-8 |
Hex Input Styles
forb accepts hex in many common formats:
691E01B8 Continuous
0x691E01B8 With 0x prefix
69 1E 01 B8 Space-separated (hex dumps)
69:1E:01:B8 Colon-separated (MAC address)
69-1E-01-B8 Dash-separated
0x69, 0x1E, 0x01, 0xB8 Comma-separated
{0x69, 0x1E, 0x01, 0xB8} C/C++ array style
Binary Input Styles
forb accepts binary in these formats:
0b10101010 With 0b prefix (standard)
0b1010_1010 With underscores for readability
%10101010 Assembly-style % prefix
1010 1010 Space-separated groups
Format Aliases
For quick filtering with --only, formats have short aliases:
| Format | Aliases |
|---|---|
| hex | h, x |
| binary | bin, b |
| octal | oct, o |
| base64 | b64 |
| datetime | ts, time, date |
| duration | dur, interval |
| decimal | dec, int, num |
| datasize | size, bytes, filesize |
| expr | expression, math, calc |
| escape | esc, escaped, cstring |
| uuid | guid |
| ulid | - |
| jwt | token |
| hash | md5, sha1, sha256, sha512 |
| ip | ipv4, ipv6 |
| color | col, rgb, argb, hsl |
| json | j |
| protobuf | proto, pb |
| plist | pl |
| url-encoded | url, percent |
| msgpack | mp, mpack |
| currency | cur, money |
| length | len, distance |
| weight | mass, kg, lb |
| volume | vol, liter, gallon |
| speed | velocity |
| pressure | psi, bar, atm |
| energy | joule, calorie, kwh |
| angle | deg, rad |
| area | sqft, sqm |
| temperature | temp, celsius, fahrenheit |
| coords | coordinates, gps, latlon, geo, location, dd, dms, ddm, utm, mgrs, geohash, pluscode |
Examples
Decoding Structured Data
)
{
}
With --packet mode, see the byte-level structure:
)
)
)
{
}
Debugging Binary Data
)
)
)
Identifying UUIDs
)
)
Decoding Timestamps
)
Analyzing Colors
)
) )
)
)
)
Math Expressions
)
Durations & Data Sizes
)
)
)
)
Escape Sequences
)
Currency Conversion
Exchange rates are fetched from the European Central Bank and cached locally.
)
SI prefixes work with currency for large amounts:
Ambiguous symbols show multiple interpretations:
Currency Expression Functions
Use currency codes as functions in expressions to convert amounts to your target currency:
)
) =
Mix currencies in expressions:
)
) ) =
Works with plugin currencies too:
Target currency is detected automatically from your system locale, or set explicitly:
# CLI flag (highest priority)
# Environment variable
FORB_TARGET_CURRENCY=SEK
# Config file (~/.config/forb/config.toml)
# [currency]
# target = "SEK"
# Show current target and available currencies
Unit Conversions
Length, weight, volume, speed, pressure, energy, angle, and area with automatic SI prefix handling:
)
)
)
Temperature
)
)
)
)
Coordinates
Multiple coordinate formats are supported and converted automatically:
)
)
)
)
Processing Logs
|
)
How It Works
Overview
┌─────────────────────────────────────────────────────────────────────────┐
│ Input: "691E01B8" │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ 1. PARSING: Try all format parsers, each returns confidence score │
│ • HexFormat.parse() → 92% (valid hex, has letters A-F) │
│ • DecimalFormat.parse() → 70% (valid number, but very large) │
│ • Base64Format.parse() → 0% (invalid base64) │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ 2. INTERPRETATION: Each successful parse produces a CoreValue │
│ • hex (92%) → CoreValue::Bytes([0x69, 0x1E, 0x01, 0xB8]) │
│ • decimal (70%) → CoreValue::Int(691_801_800) │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ 3. BFS CONVERSION: For each interpretation, explore conversion graph │
│ • Bytes → IPv4, integers, base64, hashes, text... │
│ • Int → epoch timestamp, hex notation, binary notation... │
│ • String → reinterpret as UUID, IP, JSON, datetime... │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ 4. OUTPUT: Rank by confidence, sort conversions by priority │
│ ▶ hex (92%) → ipv4, epoch-seconds, base64, binary... │
│ ▶ decimal (70%) → epoch-seconds, hex-int, binary-int... │
└─────────────────────────────────────────────────────────────────────────┘
Core Types
The system is built around three core types:
-
CoreValue: The internal representation of data. Can be
Bytes,String,Int,Float,DateTime,Json,Coordinates,Color, and various unit types (Length, Weight, etc.) -
Interpretation: Result of parsing input. Contains the
CoreValue, source format ID, confidence score (0.0-1.0), and display description. -
Conversion: Result of converting a value. Contains the target
CoreValue, format ID, display string, conversion path, and metadata (priority, kind, lossy flag).
Parsing & Confidence
Each format parser analyzes the input and returns a confidence score:
| Confidence | Meaning | Examples |
|---|---|---|
| 90-100% | Strong structural indicators | 0x prefix, UUID dashes, base64 = padding, JSON braces |
| 70-90% | Valid format, plausible content | Valid hex chars, reasonable timestamp range, valid IP octets |
| 50-70% | Ambiguous, could be multiple things | Pure digits (decimal? hex? timestamp?), short strings |
| <50% | Weak match, shown as fallback | Plain text interpretation |
Confidence is dynamic based on input characteristics. For example, math expressions:
5*9*3*9/23(complex) → 95% confidence5*9(simple multiply) → 85%2+2(simple addition) → 75% (lower because+appears in dates, URLs)
BFS Conversion Graph
Conversions are discovered via breadth-first search through a graph where:
- Nodes are
CoreValues - Edges are format conversions
┌─────────┐
│ Bytes │
└────┬────┘
┌──────────────┼──────────────┐
▼ ▼ ▼
┌─────────┐ ┌──────────┐ ┌──────────┐
│ Int-BE │ │ Base64 │ │ Text │
└────┬────┘ └──────────┘ └────┬─────┘
│ │
▼ ▼ (reinterpret)
┌─────────┐ ┌─────────┐
│ DateTime│ │ UUID │
└─────────┘ └─────────┘
The BFS explores up to 5 levels deep, tracking visited nodes to prevent cycles. Each format's conversions() method defines outgoing edges from its value type.
String Reinterpretation
When a conversion produces a CoreValue::String, the BFS re-parses that string to discover nested formats:
)
)
) # String reinterpretation!
{
}
This enables chains like:
hex → utf8 → json(hex-encoded JSON)hex → utf8 → uuid(hex-encoded UUID string)hex → utf8 → ipv4(hex-encoded IP address)base64 → utf8 → json(base64-encoded JSON)
Controlled by --reinterpret-threshold (default: 0.7). Only high-confidence reinterpretations are explored.
Conversion Kinds
Conversions are categorized by what they represent:
| Symbol | Kind | Description | Example |
|---|---|---|---|
→ |
Conversion | Actual data transformation | 1703456789 → 2023-12-24T23:06:29Z |
≈ |
Representation | Same value, different notation | 256 → 0x100 |
✓ |
Trait | Property/observation about the value | 256 → power-of-2: 2^8 |
Conversion Priority
Conversions are sorted by usefulness:
- Primary - Direct results (expression evaluation)
- Structured - JSON, MessagePack, Protobuf (pretty-printed)
- Semantic - DateTime, UUID, IP, Color (meaningful types)
- Encoding - Hex, Base64, URL-encoded (format conversions)
- Raw - Integers, bytes, hashes
Noise Control
The conversion graph can produce excessive results. Noise is controlled via:
Root-based blocking: Prevent nonsensical chains based on input type
- Text bytes → IPv4 blocked (ASCII "test" isn't
116.101.115.116) - Hex bytes → Color blocked (random hex isn't a color)
Path-based blocking: Block specific immediate conversions
- Configurable in
config.tomlvia[blocking]section
Confidence threshold: Only explore high-confidence reinterpretations
- String reinterpretation requires ≥70% confidence by default
Use -l 0 to show all conversions, or -l N to show top N.
Configuration
Settings can be configured via CLI flags, environment variables, or a config file.
Precedence: CLI args > Environment vars > Config file > Defaults
| Setting | CLI flag | Env var | Default |
|---|---|---|---|
| limit | -l, --limit |
FORB_LIMIT |
5 |
| threshold | -t, --threshold |
FORB_THRESHOLD |
0.8 |
| reinterpret_threshold | --reinterpret-threshold |
- | 0.7 |
| no_color | -C, --no-color |
FORB_NO_COLOR |
false |
| url_timeout | --url-timeout |
FORB_URL_TIMEOUT |
30 |
| url_max_size | --url-max-size |
FORB_URL_MAX_SIZE |
10M |
| target_currency | --currency |
FORB_TARGET_CURRENCY |
locale/USD |
# Show config file location
# Generate default config file
Priority & Blocking
Customize which conversions are shown and in what order:
# ~/.config/forb/config.toml (Linux) or ~/Library/Application Support/forb/config.toml (macOS)
[]
# Reorder categories (default: Primary, Structured, Semantic, Encoding, Raw)
= ["Semantic", "Structured", "Primary", "Encoding", "Raw"]
# Adjust individual format priorities
[]
= 10 # Bump up within category
= 5 # Also bump up, but less
= -10 # Push down within category
= "Primary" # Move to different category
[]
# Never show these formats
= ["octal", "binary"]
# Block specific conversion paths
= ["hex:msgpack", "uuid:epoch-seconds"]
Use --show-paths to see blockable paths for any input:
)
Plugins
Extend forb with Python plugins for custom decoders, expression functions, traits, currencies, and more. Requires Python 3.8+ installed on your system.
Bundled Plugin: A cryptocurrency plugin (BTC, ETH, SOL rates from CoinGecko) is installed automatically on first run.
# Try the bundled crypto plugin
# Enable more sample plugins
# Use plugin functionality
Plugin types:
- Decoders - Parse custom input formats
- Expression variables - Add constants like
PI,E,PHI - Expression functions - Add functions like
factorial(),fib(),gcd() - Traits - Detect properties like "semantic version" or "well-known port"
- Visualizers - Custom rich display for GUI applications
- Currencies - Custom exchange rates (e.g., cryptocurrencies) with automatic cross-conversion
# List loaded plugins
# Show plugin directory
See PLUGINS.md for comprehensive documentation on creating and using plugins.
Analytics
Local usage tracking helps improve forb. Enabled by default, stored in human-readable TOML.
Privacy-first design:
- No input data, filenames, or URLs are ever recorded
- Only aggregate counts: which formats are used, which features, CLI version
- Data stored locally at
~/.config/forb/analytics.toml - Disable anytime via
FORB_ANALYTICS=0or config
# View analytics status and summary
# View full analytics data
# Clear all analytics data
# Disable analytics
# Or add to config: [analytics] enabled = false
Anonymous Contribution
Optionally share aggregate usage data to help prioritize development:
# Preview what would be sent (no network call)
# Send anonymous data
What's sent: CLI version, platform, top 10 formats/conversions, feature usage counts. Fresh random ID per contribution (no cross-session tracking).
License
MIT
Contributing
Contributions welcome! See CLAUDE.md for architecture details and coding conventions.