> ## Documentation Index
> Fetch the complete documentation index at: https://iso8583sim.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Reference

> iso8583sim provides a command-line interface for parsing, building, and validating ISO 8583 messages.

## Installation

The CLI is included with iso8583sim:

```bash theme={null}
pip install iso8583sim
```

## Basic Usage

```bash theme={null}
# 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.

```bash theme={null}
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:**

```bash theme={null}
# 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.

```bash theme={null}
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:**

```bash theme={null}
# 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:**

```json theme={null}
{
    "2": "4111111111111111",
    "3": "000000",
    "4": "000000010000",
    "11": "123456",
    "41": "TERM0001",
    "42": "MERCHANT123456 "
}
```

### validate

Validate an ISO 8583 message for structure and content.

```bash theme={null}
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:**

```bash theme={null}
# 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.

```bash theme={null}
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:**

```bash theme={null}
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](../core/convert) for the rules.

### explain

Explain a message in plain English.

```bash theme={null}
iso8583sim explain MESSAGE [OPTIONS]
```

By default the explanation comes from an LLM (see [LLM Features](../llm) 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:**

```bash theme={null}
# 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`.

```bash theme={null}
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:**

```bash theme={null}
# 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](../net) for the rules file format.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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]`.

```bash theme={null}
iso8583sim web [--host 127.0.0.1] [--port 8000] [--reload]
```

Interactive API docs are served at `/docs`. See [REST API](../web).

### mcp

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

```bash theme={null}
iso8583sim mcp
```

Your MCP client normally starts this command for you. See [MCP Server](../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

```bash theme={null}
iso8583sim parse "0100..." --format json
```

```json theme={null}
{
    "mti": "0100",
    "bitmap": "7024058020C09000",
    "fields": {
        "2": "4111111111111111",
        "3": "000000",
        "4": "000000010000"
    },
    "network": "VISA"
}
```

### Raw

```bash theme={null}
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

```bash theme={null}
# 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":**

```bash theme={null}
# Ensure iso8583sim is in PATH
pip show iso8583sim  # Check installation
python -m iso8583sim.cli --help  # Alternative invocation
```

**"Invalid hex string":**

```bash theme={null}
# Ensure message contains only hex characters (0-9, A-F)
# Remove any spaces or newlines
```

**"Parse error: Invalid bitmap":**

```bash theme={null}
# Check that bitmap is 16 hex characters
# Primary bitmap must be exactly 8 bytes (16 hex chars)
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.