# How to Use the GeoIP CLI for Batch Processing Multiple Conversion Tasks

> Unlock efficient GeoIP data processing with the loyalsoldier/geoip CLI. Learn to batch convert multiple IP tasks using a single JSON configuration file for streamlined workflows.

- Repository: [Loyalsoldier/geoip](https://github.com/loyalsoldier/geoip)
- Tags: how-to-guide
- Published: 2026-03-06

---

**The GeoIP CLI supports batch processing through a single `convert` command that executes multiple input-to-output pipelines defined in a JSON configuration file.**

The `loyalsoldier/geoip` repository provides a purpose-built command-line interface for high-volume GeoIP data transformation. Unlike traditional tools requiring separate invocations per file, this CLI implements **GeoIP CLI batch processing** through a configuration-driven engine that executes complex multi-format workflows in a single process.

## Architecture of the Batch Processing Engine

### The Instance Orchestrator

The core of the batch system is the `Instance` type defined in [`lib/instance.go`](https://github.com/loyalsoldier/geoip/blob/main/lib/instance.go). This struct maintains slices of `InputConverter` and `OutputConverter` interfaces that represent your conversion pipeline. When initialized, the orchestrator assembles these slices based on your configuration, enabling sequential processing of multiple data sources and output formats without manual intervention ([source](https://github.com/Loyalsoldier/geoip/blob/master/lib/instance.go)).

### Configuration Parsing with `InitConfigFromBytes`

Configuration parsing occurs through `Instance.InitConfigFromBytes`, which handles JSON with comment support via the `hujson` library. This method populates the internal `input` and `output` slices with concrete converter implementations mapped from the `type` strings in your configuration file ([source](https://github.com/Loyalsoldier/geoip/blob/master/lib/instance.go#L52-L68)).

### Execution Flow and the `Run` Method

The `Instance.Run` method implements the actual batch logic. It creates a fresh `Container` object, then executes `RunInput` for every configured input to aggregate data, followed by `RunOutput` for every configured output to write results ([source](https://github.com/Loyalsoldier/geoip/blob/master/lib/instance.go#L11-L27)). This architecture ensures that multiple input sources are merged into a single dataset before being distributed to all output formats, completing the entire batch in one memory-efficient pass.

### CLI Entry Point in [`convert.go`](https://github.com/loyalsoldier/geoip/blob/main/convert.go)

The user-facing interface resides in [`convert.go`](https://github.com/loyalsoldier/geoip/blob/main/convert.go), which registers the `convert` sub-command using the Cobra framework. This file binds the `--config` flag and launches the pipeline by calling `NewInstance().InitConfig(...).Run()` ([source](https://github.com/Loyalsoldier/geoip/blob/master/convert.go#L10-L35)).

## Configuring Multiple Conversion Tasks

### Input and Output Arrays

To enable batch processing, define all conversion tasks in a single JSON file with top-level `input` and `output` arrays. Each object in the `input` array specifies a data source and format, while each object in the `output` array defines a destination format and path. The CLI processes these arrays sequentially, executing every input-to-output permutation defined in the configuration.

### Supported Format Plugins

The [`lib/config.go`](https://github.com/loyalsoldier/geoip/blob/main/lib/config.go) file defines the JSON schema and maps `type` strings to concrete implementations in the `plugin/` directory. For example, [`plugin/v2ray/dat_in.go`](https://github.com/loyalsoldier/geoip/blob/main/plugin/v2ray/dat_in.go) provides the V2Ray DAT reader, while [`plugin/mihomo/mrs_out.go`](https://github.com/loyalsoldier/geoip/blob/main/plugin/mihomo/mrs_out.go) implements the MRS writer. This plugin architecture allows you to mix heterogeneous formats—such as V2Ray DAT, MaxMind MMDB, and plain text—within the same batch job.

### Example Configuration File

The following [`config.json`](https://github.com/loyalsoldier/geoip/blob/main/config.json) demonstrates three independent conversion jobs executing in one batch: converting a V2Ray DAT to text, a MaxMind MMDB to MMDB, and a text file to Sing-Box SRS format.

```json
{
  "input": [
    { "type": "v2rayGeoIPDat", "source": "./geoip.dat", "action": "add" },
    { "type": "maxmindMMDB",   "source": "./GeoLite2-Country.mmdb", "action": "add" },
    { "type": "text",          "source": "./cn.txt", "action": "add" }
  ],
  "output": [
    { "type": "text",          "target": "./output/text/cn.txt", "action": "output" },
    { "type": "maxmindMMDB",   "target": "./output/mmdb/Country.mmdb", "action": "output" },
    { "type": "singboxSRS",    "target": "./output/srs/cn.srs", "action": "output" }
  ]
}

```

## Running Batch Conversions

### Local Configuration Execution

Execute the batch workflow by invoking the `convert` command with the local configuration file:

```bash
geoip convert -c config.json

```

The CLI outputs progress for each pipeline stage, processing all inputs and generating all outputs defined in the configuration.

### Remote Configuration for CI Pipelines

For automated environments, `Instance.InitConfig` detects `http://` or `https://` schemes in the configuration path and retrieves the file via `GetRemoteURLContent`. This allows centralized configuration management in CI/CD pipelines:

```bash
geoip convert -c https://raw.githubusercontent.com/yourfork/geoip/master/config.json

```

### Chaining with the Merge Command

Advanced batch workflows can preprocess data using the `merge` sub-command defined in [`merge.go`](https://github.com/loyalsoldier/geoip/blob/main/merge.go). This command aggregates CIDR lists from stdin and passes the resulting container to the conversion stage, enabling dynamic data preparation before static batch execution:

```bash
curl -s https://example.com/cidr1.txt https://example.com/cidr2.txt | \
  geoip merge -t ipv4 | \
  geoip convert -c config.json

```

## Summary

- **Single-command batching**: The `convert` command processes multiple input-to-output pipelines defined in one JSON configuration file.
- **Container-based architecture**: The `Instance.Run` method in [`lib/instance.go`](https://github.com/loyalsoldier/geoip/blob/main/lib/instance.go) aggregates all inputs into a shared `Container` before distributing to all outputs, ensuring consistent data across batch tasks.
- **Plugin-driven formats**: The system supports mixing V2Ray DAT, MaxMind MMDB, Sing-Box SRS, and text formats within the same batch job through the plugin system.
- **Remote configuration**: The CLI fetches HTTP(S) configurations automatically via `GetRemoteURLContent`, enabling centralized batch management.
- **Pipeline chaining**: The `merge` command integrates with `convert` for stdin-based preprocessing before batch execution.

## Frequently Asked Questions

### Can I process multiple input files to one output file in a single batch?

Yes. Define multiple entries in the `input` array with `action: "add"` and a single entry in the `output` array. The `Instance.Run` method aggregates all inputs into one container before writing to the specified output, effectively merging sources during the batch process.

### Does the CLI support remote configuration files?

Yes. When the `--config` argument begins with `http://` or `https://`, the `InitConfig` method in [`lib/instance.go`](https://github.com/loyalsoldier/geoip/blob/main/lib/instance.go) invokes `GetRemoteURLContent` to fetch the JSON before parsing. This allows you to store batch configurations in version control and invoke them directly in CI/CD scripts.

### How do I chain the merge command with batch conversion?

Use the `merge` sub-command to aggregate and filter CIDR data via stdin, then pipe the result into `geoip convert`. The merge command outputs a container-compatible stream that feeds into the conversion pipeline, allowing preprocessing before the batch workflow defined in your configuration file executes.

### What file formats support batch input and output operations?

The CLI supports heterogeneous batch operations across all implemented plugins. Inputs include `v2rayGeoIPDat`, `maxmindMMDB`, and `text`, while outputs include `text`, `maxmindMMDB`, and `singboxSRS`. You can mix any combination of these formats in a single configuration file, and the system will execute all conversions in the defined sequence.