CLI Reference

Installation

The CLI is included with iso8583sim:

pip install iso8583sim

Basic Usage

# Get help
iso8583sim --help

# Parse a message
iso8583sim parse "0100702406C120E09000..."

# Build a message
iso8583sim build --mti 0100 --fields fields.json

# Validate a message
iso8583sim validate "0100702406C120E09000..."

# Generate sample messages
iso8583sim generate --type auth --pan 4111111111111111

Commands

parse

Parse a raw ISO 8583 message and display its contents.

iso8583sim parse MESSAGE [OPTIONS]

Arguments:

Argument	Description
`MESSAGE`	Raw ISO 8583 message as hex string

Options:

Option	Description
`--version`	ISO 8583 version (1987, 1993, 2003)
`--network`	Card network (visa, mastercard, amex, etc.)
`--format`	Output format (table, json, raw)
`--verbose`	Show detailed field information

Examples:

# Basic parsing
iso8583sim parse "0100702406C120E09000..."

# With version specification
iso8583sim parse "0100..." --version 1993

# JSON output
iso8583sim parse "0100..." --format json

# Verbose output with field descriptions
iso8583sim parse "0100..." --verbose

build

Build an ISO 8583 message from field values.

iso8583sim build [OPTIONS]

Options:

Option	Description
`--mti`	Message Type Indicator (required)
`--fields`	JSON file with field values
`--field`	Individual field (can be repeated): `--field 2=4111111111111111`
`--version`	ISO 8583 version
`--output`	Output file (default: stdout)

Examples:

# Build from JSON file
iso8583sim build --mti 0100 --fields fields.json

# Build with inline fields
iso8583sim build --mti 0100 \
    --field 2=4111111111111111 \
    --field 3=000000 \
    --field 4=000000010000

# Save to file
iso8583sim build --mti 0100 --fields fields.json --output message.hex

fields.json format:

{
    "2": "4111111111111111",
    "3": "000000",
    "4": "000000010000",
    "11": "123456",
    "41": "TERM0001",
    "42": "MERCHANT123456 "
}

validate

Validate an ISO 8583 message for structure and content.

iso8583sim validate MESSAGE [OPTIONS]

Options:

Option	Description
`--network`, `-n`	Validate against one network’s requirements
`--against`, `-a`	Check against several networks: comma separated names, or `all`
`--version`, `-v`	ISO 8583 version (1987, 1993, 2003)

Examples:

# Basic validation
iso8583sim validate "0100..."

# With network validation
iso8583sim validate "0100..." --network visa

# Which networks would accept this message?
iso8583sim validate "0100..." --against all

Output (--against all):

                       Network Compliance
┏━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Network    ┃ Result ┃ Issues                                 ┃
┡━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ VISA       │ PASS   │ -                                      │
│ MASTERCARD │ PASS   │ -                                      │
│ UNIONPAY   │ FAIL   │ Required field 49 missing for UNIONPAY │
└────────────┴────────┴────────────────────────────────────────┘

The command exits with status 1 when any check fails.

convert

Convert a message to another ISO 8583 version.

iso8583sim convert MESSAGE --to VERSION [OPTIONS]

Options:

Option	Description
`--to`, `-t`	Target version (1987, 1993, 2003)
`--from`, `-f`	Version of the input message (default 1987)
`--network`, `-n`	Card network. Network rules are only enforced on the output when this is given
`--output`, `-o`	Output file

Example:

iso8583sim convert "0400..." --to 2003

The output shows the converted message, notes about fields whose meaning differs between versions, and any fields that had to be dropped. See Version Conversion for the rules.

explain

Explain a message in plain English.

iso8583sim explain MESSAGE [OPTIONS]

By default the explanation comes from an LLM (see LLM Features for provider setup). With --no-llm you get a rule-based summary instead, which works offline and needs no API key. Options:

Option	Description
`--no-llm`	Rule-based summary, no LLM or API key needed
`--provider`, `-p`	LLM provider: `anthropic`, `openai`, `google` or `ollama`. Auto-detected if omitted
`--model`, `-m`	Model name for the provider
`--verbose`	Ask the LLM for more technical detail
`--version`, `-v`	ISO 8583 version (1987, 1993, 2003)
`--network`, `-n`	Card network (detected from the PAN if omitted)

Examples:

# Explain with the first configured LLM provider
iso8583sim explain "0100..."

# Use a specific provider and model
iso8583sim explain "0100..." --provider ollama --model qwen3

# Offline, rule-based summary
iso8583sim explain "0110..." --no-llm

Output (--no-llm):

MTI 0110: authorization response from acquirer. Card network: MASTERCARD. Card:
555555******4444. Transaction type: Purchase. Amount: 25.00 EUR. Response code 51:
Insufficient funds. Terminal: TERM0001. Merchant: MERCHANT123456.

followed by a table of every field.

generate

Generate sample ISO 8583 messages from a template, or from a plain English description with --llm.

iso8583sim generate [OPTIONS]

Options:

Option	Description
`--type`, `-t`	Message type (auth, financial, reversal, network). Required unless `--llm` is given
`--pan`, `-p`	Primary Account Number
`--amount`, `-a`	Amount in minor units (`1000` is 10.00), or a decimal such as `10.00`. Uses the currency’s decimal places, so JPY `1500` is 1500 yen
`--currency`, `-c`	Currency code (ISO 4217, default 840)
`--network`, `-n`	Card network
`--llm`, `-l`	Describe the message in plain English and let an LLM build it
`--provider`	LLM provider for `--llm`
`--model`	Model name for `--llm`
`--output`, `-o`	Output file

Examples:

# Generate authorization request
iso8583sim generate --type auth --pan 4111111111111111 --amount 10000

# Save to file
iso8583sim generate --type auth --output message.txt

# Generate from a description
iso8583sim generate --llm "$50 refund to a Mastercard at ACME Store"

With --llm, the generated message is validated before it’s shown, and common problems are fixed automatically.

serve

Run a mock issuer host that answers requests by rules. See Networking for the rules file format.

iso8583sim serve [--host 127.0.0.1] [--port 8583] [--rules rules.yaml] [--format bcd] [--header 2b] [--tpdu 6000010000]

Stops on Ctrl+C or SIGTERM and prints a summary of the requests it received and how it answered them.

send

Send one message to a host and show the response.

iso8583sim send MESSAGE [--host 127.0.0.1] [--port 8583] [--format ascii-binary] [--header 2b] [--tpdu HEX] [--timeout 10]

Exits with status 1 on a timeout or connection error.

load

Send many generated requests to a host and report throughput, latency percentiles and response codes.

iso8583sim load [--host 127.0.0.1] [--port 8583] [--count 1000] [--concurrency 10] [--connections 1] [--network VISA]

Takes the same --format, --header, --tpdu and --timeout options as send. Exits with status 1 if any request timed out or failed.

web

Run the REST API server. Requires pip install iso8583sim[web].

iso8583sim web [--host 127.0.0.1] [--port 8000] [--reload]

Interactive API docs are served at /docs. See REST API.

mcp

Run the MCP server over stdio so AI assistants can use iso8583sim. Requires pip install iso8583sim[mcp].

iso8583sim mcp

Your MCP client normally starts this command for you. See MCP Server for setup.

Output Formats

Table (default)

┌─────────┬───────────────────────────┬────────────────────────┐
│ Field   │ Value                     │ Description            │
├─────────┼───────────────────────────┼────────────────────────┤
│ MTI     │ 0100                      │ Authorization Request  │
│ 2       │ 4111111111111111          │ Primary Account Number │
│ 3       │ 000000                    │ Processing Code        │
│ 4       │ 000000010000              │ Amount                 │
└─────────┴───────────────────────────┴────────────────────────┘

JSON

iso8583sim parse "0100..." --format json

{
    "mti": "0100",
    "bitmap": "7024058020C09000",
    "fields": {
        "2": "4111111111111111",
        "3": "000000",
        "4": "000000010000"
    },
    "network": "VISA"
}

Raw

iso8583sim parse "0100..." --format raw

0100
7024058020C09000
2: 4111111111111111
3: 000000
4: 000000010000

Exit Codes

Code	Meaning
0	Success
1	Parse error
2	Validation error
3	Build error
4	File not found

Environment Variables

Variable	Description
`ISO8583SIM_VERSION`	Default ISO 8583 version
`ISO8583SIM_NETWORK`	Default card network
`ANTHROPIC_API_KEY`	For LLM features
`OPENAI_API_KEY`	For LLM features

Piping and Scripting

# Pipe messages
cat messages.txt | while read line; do
    iso8583sim parse "$line" --format json
done

# Parse from file
iso8583sim parse "$(cat message.hex)"

# Build and parse roundtrip
iso8583sim build --mti 0100 --fields fields.json | iso8583sim parse -

Troubleshooting

Common Issues

“Command not found”:

# Ensure iso8583sim is in PATH
pip show iso8583sim  # Check installation
python -m iso8583sim.cli --help  # Alternative invocation

“Invalid hex string”:

# Ensure message contains only hex characters (0-9, A-F)
# Remove any spaces or newlines

“Parse error: Invalid bitmap”:

# Check that bitmap is 16 hex characters
# Primary bitmap must be exactly 8 bytes (16 hex chars)

Get started

Core

Card networks

Tools and interfaces

LLM features

Architecture

Operations

Installation

Basic Usage

Commands

parse

build

validate

convert

explain

generate

serve

send

load

web

mcp

Output Formats

Table (default)

JSON

Raw

Exit Codes

Environment Variables

Piping and Scripting

Troubleshooting

Common Issues

​Installation

​Basic Usage

​Commands

​parse

​build

​validate

​convert

​explain

​generate

​serve

​send

​load

​web

​mcp

​Output Formats

​Table (default)

​JSON

​Raw

​Exit Codes

​Environment Variables

​Piping and Scripting

​Troubleshooting

​Common Issues

Installation

Basic Usage

Commands

parse

build

validate

convert

explain

generate

serve

send

load

web

mcp

Output Formats

Table (default)

JSON

Raw

Exit Codes

Environment Variables

Piping and Scripting

Troubleshooting

Common Issues