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

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. 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).

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).

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). 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

The user-facing interface resides in 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).

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 file defines the JSON schema and maps type strings to concrete implementations in the plugin/ directory. For example, plugin/v2ray/dat_in.go provides the V2Ray DAT reader, while 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 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.

{
  "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:

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:

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. This command aggregates CIDR lists from stdin and passes the resulting container to the conversion stage, enabling dynamic data preparation before static batch execution:

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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}