Command-Line Interface Reference

This page describes the configuration flags and command-line options available in image-syncer.

To view the help output and verify your installation, run the binary with the -h or --help flag:

image-syncer --help

---

Global Command-Line Flags

Flag	Shorthand	Default Value	Description
--auth	-	"" (or auth.json)	Path to the registry credentials file. Must be used with --images.
--images	-	"" (or images.json)	Path to the synchronization rules file. Must be used with --auth.
--config	-	"" (or config.json)	Path to a legacy combined configuration file. Deprecated; use --auth and --images instead.
--proc	-p	5	Maximum number of concurrent worker goroutines in the transfer pool.
--retries	-r	2	Number of retry attempts for failed tasks. Retries run after the initial task queue finishes.
--log	-	Stderr	File path for writing operational logs. If empty, logs are written to standard error.
--os	-	[] (Empty)	Limits synchronization of multi-architecture images to the specified operating systems (e.g., linux, windows).
--arch	-	[] (Empty)	Limits synchronization of multi-architecture images to the specified hardware architectures (e.g., amd64, arm64).
--force	-	false	Skips checking if the manifest already exists at the destination, forcing an update of target manifests.
--output-success-images	-	""	Path to a file where the list of successfully synchronized image tags will be written.
--output-images-format	-	"yaml"	Format for the success output file. Supported values: yaml or json.

---

Detailed Configuration Scenarios

1. Fine-Tuning Concurrency and Retries

To optimize transfer speeds on high-bandwidth networks, you can increase the concurrent worker pool. To handle transient network issues or registry rate limits, increase the retry count:

image-syncer 
  --auth=./auth.yaml \
  --images=./images.yaml \
  --proc=12 \
  --retries=5 \
  --log=./sync-run.log

• Setting --proc: Choose a value based on your network and CPU limits. High concurrency on slow connections can cause network congestion and lead to timeout errors.
• Setting --retries: Failed transfers are queued and retried after the main task queue finishes, helping to recover from transient errors.

2. Multi-Architecture Platform Filtering

To save storage space on your destination registry, you can filter multi-architecture manifests to transfer only the platforms your environment needs. This example copies only 64-bit Linux layers:

image-syncer \
  --auth=./auth.yaml \
  --images=./images.yaml \
  --os=linux \
  --arch=amd64

You can also specify multiple platforms by repeating the flags or using comma-separated lists, depending on your system shell environment:

image-syncer \
  --auth=./auth.yaml \
  --images=./images.yaml \
  --os=linux,windows \
  --arch=amd64,arm64

3. Verification and Automation Logs

For automated pipelines, you can output a list of successfully synchronized images. This is useful for passing the newly synchronized tags to downstream deployment tasks:

image-syncer \
  --auth=./auth.yaml \
  --images=./images.yaml \
  --output-success-images=./completed-syncs.json \
  --output-images-format=json

Upon completion, the output JSON file will contain an array of the synchronized target images:

[
  "localhost:5000/image-syncer-test/alpine:3.18.2"
]

If you encounter execution errors or registry connection failures, see the Troubleshooting & FAQs page.