galaxio-cli

galaxio-cli

galaxio is a CLI for Gatling performance testing workflows. It scaffolds new load-test projects from templates and generates Gatling scripts from API specifications.

Key features:

• template init — scaffold a ready-to-compile Gatling project from a template
• template list — discover available templates from any registry
• generate swagger / har / postman — generate Gatling scripts from an existing API spec
• doctor — validate CLI configuration and registry access
• update — self-update from GitHub Releases

Install

Supported platforms

OS	Arch	go install	Shell installer	Manual download
macOS (darwin)	amd64	yes	yes	yes
macOS (darwin)	arm64 (Apple Silicon)	yes	yes	yes
Linux	amd64	yes	yes	yes
Linux	arm64	yes	yes	yes
Windows	amd64	yes	no*	yes
Windows	arm64	yes	no*	yes

* The shell installer targets POSIX shells. Windows users should use go install or download a .zip from GitHub Releases (see below).

Option 1 — go install (all platforms)

Requires Go 1.24 or later on your PATH.

go install github.com/galax-io/galaxio-cli/cmd/galaxio@latest

The binary is placed in $(go env GOPATH)/bin. Make sure that directory is on your PATH (see PATH setup).

Option 2 — Shell installer (macOS and Linux)

Prerequisites: curl, shasum, tar, unzip.

curl -fsSL https://raw.githubusercontent.com/galax-io/galaxio-cli/main/scripts/install.sh | sh

Pin a specific version:

curl -fsSL https://raw.githubusercontent.com/galax-io/galaxio-cli/main/scripts/install.sh | GALAXIO_VERSION=0.1.1 sh

The installer writes to $HOME/.local/bin by default. Override with GALAXIO_BIN_DIR:

curl -fsSL https://raw.githubusercontent.com/galax-io/galaxio-cli/main/scripts/install.sh | GALAXIO_BIN_DIR=/usr/local/bin sh

Option 3 — Manual download (all platforms)

Download a prebuilt binary from the GitHub Releases page. Archives are named galaxio_<version>_<os>_<arch>.tar.gz (.zip on Windows).

1. Download the archive for your platform.
2. Verify the checksum against checksums.txt from the same release.
3. Extract the galaxio binary (or galaxio.exe on Windows).
4. Move it to a directory on your PATH.

Option 4 — Docker image

The image is published to Docker Hub as galaxioteam/galaxio:<release-version>, plus the alias galaxioteam/galaxio:<major.minor> and galaxioteam/galaxio:latest. The badges at the top show the current Docker Hub tag, the latest release utility size, and the compressed Docker image size.

docker pull galaxioteam/galaxio:0.1.1
docker pull galaxioteam/galaxio:0.1
docker pull galaxioteam/galaxio:latest
docker run --rm galaxioteam/galaxio --help

For commands that create files, mount a working directory and set it as the container workdir:

docker run --rm -v "$PWD":/work -w /work galaxioteam/galaxio template list

Windows

Windows does not ship with a POSIX shell, so use one of:

1. go install — simplest if Go is already installed.
2. Manual download — grab the .zip from GitHub Releases, extract galaxio.exe, and place it in a directory listed in your Path environment variable (for example C:\Users\<you>\bin).

To add a directory to your Path on Windows:

setx Path "%Path%;C:\Users\<you>\bin"

Then open a new terminal for the change to take effect.

PATH setup

After installing, verify the binary is reachable:

galaxio --version

If the command is not found, add the install location to your PATH:

macOS / Linux (shell installer default)

# Add to ~/.bashrc, ~/.zshrc, or equivalent:
export PATH="$HOME/.local/bin:$PATH"

macOS / Linux (go install default)

export PATH="$(go env GOPATH)/bin:$PATH"

Windows

setx Path "%Path%;%USERPROFILE%\go\bin"

Troubleshooting installation

command not found after install

The binary is not on your PATH. Check where it was installed:

ls ~/.local/bin/galaxio        # shell installer default
ls "$(go env GOPATH)/bin/galaxio"  # go install default

Open a new terminal after changing PATH.

unsupported arch from the shell installer

The installer only recognises x86_64/amd64 and arm64/aarch64. For other architectures (e.g. armv7l), use go install instead.

GitHub API / network / proxy errors

Symptom	Likely cause	Fix
curl: (7) Failed to connect	Corporate proxy or firewall	Set https_proxy before running the installer: https_proxy=http://proxy:port sh scripts/install.sh
curl: (28) Connection timed out	Slow or blocked network	Retry, or download the binary manually
HTTP 403 / rate-limit error	GitHub API rate limit (60 req/h unauthenticated)	Wait an hour, or download manually from the Releases page
release asset not found	OS/arch not in the release	Verify your platform is in the support matrix; fall back to go install

Checksum verification fails

The download may be corrupted. Delete the partial install and retry:

rm -f ~/.local/bin/galaxio
curl -fsSL https://raw.githubusercontent.com/galax-io/galaxio-cli/main/scripts/install.sh | sh

Usage

galaxio --help          # show commands and flags
galaxio version         # print build info
galaxio report gatling  # read the latest Gatling run and report what it holds
galaxio --verbose ...   # verbose diagnostic output
galaxio --quiet ...     # suppress non-error output
galaxio --no-color ...  # disable colour

Update galaxio from GitHub Releases:

galaxio update
galaxio update --dry-run
galaxio update --version 0.1.1

Generate shell completions:

galaxio completion bash
galaxio completion zsh
galaxio completion fish

# Install for zsh:
mkdir -p ~/.zsh/completion
galaxio completion zsh > ~/.zsh/completion/_galaxio

Reporting Ecosystem

Galaxio uses one canonical name for each reporting component:

• parsec is the public result-primitives library at github.com/galax-io/parsec.
• galaxio report is the CLI namespace for finished-run reporting.

See the naming and licence decision record for the selected identities and rejected alternatives.

Read a finished run

galaxio report <tool> [PATH] reads a finished run once and reports what it holds. It computes no statistic and writes no data format; statistics and Gatling's own stats.json follow in later releases.

galaxio report gatling                               # the latest run under target/gatling
galaxio report gatling target/gatling/mysim-20260906044741110
galaxio report gatling path/to/simulation.log
galaxio report gatling build/reports/gatling         # a results root: lastRun.txt, else the newest run
galaxio report                                       # help

run         io.galaxio.parsec.corpus.CorpusSimulation
id          io.galaxio.parsec.corpus.CorpusSimulation
started     2026-09-06T04:48:14.356Z
tool        gatling 3.15.1
log         binary, target/gatling/mysim-20260906044741110/simulation.log
found by    path
span        2026-09-06T04:48:14.885Z .. 2026-09-06T04:48:18.117Z (3.232s)
requests    102 (84 ok, 18 ko)
groups      12 traversals
users       12 events
errors      6
assertions  10 payloads the run declared

Tool. The first argument names the tool that produced the run. gatling is the only tool this release reads: text logs from Gatling 3.11.5 through 3.12.0 and binary logs from 3.13.1 through 3.15.1, identified from the log's content, never its name. A version below that range, and 3.13.0, are refused with a message naming the version and the range; a newer version is read and a warning goes to standard error.

PATH. A run directory, its simulation.log, or a results root holding run directories. With no path the Maven and sbt results root target/gatling is searched (Gradle writes to build/reports/gatling; pass it). In a results root the run named by lastRun.txt wins if it still exists, otherwise the most recently modified run. The report says which run was read and by which rule.

What the report says. started is the run's own recorded start and span is the interval the run actually covers, which is a different quantity; the span line is left out when the log holds an item the source could not place in time. requests splits by the outcome the source recorded, never inferred, and a further unknown line appears only when the source lost a sample's outcome, counting those requests apart rather than guessing either way. groups counts traversals and users counts events, each saying so, because a run enters a group once per iteration and emits a start and an end per virtual user. assertions counts the opaque payloads the run declared, wherever the log put them, and is left out when it declared none. Anything the log recorded is quoted if it is not printable, so a run from somebody else's CI cannot colour your terminal or erase the line it is on. --quiet suppresses the report and leaves errors, and the unverified-version warning, which qualifies every number under it; --verbose adds what this source can never record, such as a response code, which Gatling does not put in its log.

-o. Reserved for report formats later releases produce: stats and global_stats (Gatling's own stats.json and global_stats.json) and yml (the OpenNFR YAML report). Every name in the list is checked, and any value exits 2: a known name naming the release that delivers it, or saying it is postponed where no release is set yet, and an unknown one listing the names that exist. The value is refused as the flag is parsed, so --help does not get past it either. There is no -o json and no -o text: the first machine-readable output this command publishes will be Gatling's own stats.json, in Gatling's schema and with Gatling's numbers.

Exit codes. 0 when the run was read to the end; 1 for a runtime failure — no run under the directory, a path that cannot be read, a log that is not a Gatling simulation.log, an unsupported version, a log cut short (the counts of what it did hold are still reported, so a script cannot mistake a partial run for a complete one), or a damaged log (no counts, because the records before the damage are not a result); 2 for a usage error — an unsupported tool, an empty or third argument, an unknown flag, or any -o, which is rejected while the flag is parsed and so before any help. An interrupt cancels the read and exits 1 naming the log it stopped in.

Template Workflow

The CLI ships with a default registry (github:galax-io/galaxio-template-registry). Template discovery works out of the box — no configuration needed.

List available templates

galaxio template list
galaxio template list -o json

Scaffold a project

Files are written to --destination (defaults to the current directory):

galaxio template init gatling/scala-sbt -d ./perf-tests

# Override template inputs
galaxio template init gatling/scala-sbt \
  --set Name=orders-api \
  --set Package=org.example.perf \
  --set PackagePath=org/example/perf \
  -d ./perf-tests

# Supply inputs from a YAML file
galaxio template init gatling/scala-sbt --values ./values.yaml -d ./perf-tests

Enable optional plugins

Gatling templates support optional Kafka, JDBC, and AMQP plugin modules:

galaxio template init gatling/scala-sbt \
  --set KafkaPluginEnabled=true \
  --set Name=orders-api \
  -d ./perf-tests

See templates-gatling for the full list of available templates and inputs.

Scaffold and overlay generated files together

Use --init on a generate command to scaffold a full project first, then overlay the generated API files on top in one step:

galaxio generate swagger --from ./petstore.yaml --init -d ./perf-tests

Custom registries

The default registry is used automatically. Override it only when you need a different source:

galaxio template configure --registry github:my-org/my-registry
galaxio template configure --show   # inspect current setting

# Override for a single command without changing config
galaxio template init mypack/mytemplate --registry local:/path/to/registry

Registry source formats:

Format	Example	Notes
github:owner/repo	github:galax-io/templates-gatling	Resolves pack version to GitHub release tag v{version}
local:path	local:../my-templates	Resolved from current working directory

Validate a template pack

galaxio template validate local:./my-pack
galaxio template validate github:my-org/my-templates

Clear the template cache

Downloaded GitHub template archives are cached locally. Clear the cache when you need to force a fresh download:

galaxio template clear-cache

Code Generation

Generate Gatling load-test scripts from existing API specifications. The --template flag selects the Gatling DSL flavour (default: scala-sbt).

From Swagger / OpenAPI

galaxio generate swagger --from ./petstore.yaml
galaxio generate swagger --from ./petstore.yaml --dest ./out
galaxio generate swagger --from ./petstore.yaml --package org.example.perf
galaxio generate swagger --from ./petstore.yaml -o json   # machine-readable summary

From HAR recording

galaxio generate har --from ./recording.har
galaxio generate har --from ./recording.har --dest ./out --include-static

From Postman collection

galaxio generate postman --from ./collection.json
galaxio generate postman --from ./collection.json --dest ./out

Conflict strategy (--if-exists)

When generating into a directory that already contains files, control how conflicts are resolved:

Strategy	Behaviour
suffix (default)	Writes file.generated.scala alongside the existing file.scala
merge	Writes conflict markers (<<<< generated / ==== / >>>> existing) into the existing file
skip	Leaves the existing file untouched and emits a warning to stderr
overwrite	Replaces the existing file; skips the write if content is identical

galaxio generate swagger --from ./petstore.yaml --if-exists overwrite
galaxio generate swagger --from ./petstore.yaml --if-exists skip

Diagnostics

Check CLI configuration and registry connectivity:

galaxio doctor
galaxio doctor --registry github:my-org/my-registry
galaxio doctor -o json

doctor verifies that the configured registry is reachable, the pack manifest is valid, and all declared templates can be resolved.

Environment Variables

Variable	Default	Purpose
GALAXIO_CONFIG	~/.galaxio/config.yaml	Override the config file path (useful in CI or Docker)
GALAXIO_CACHE_DIR	OS user cache dir	Override the template cache directory

Exit Codes

Code	Meaning
0	Command completed successfully.
1	Runtime failure while executing a valid command.
2	Usage error — invalid flags, arguments, or commands.

Build From Source

git clone https://github.com/galax-io/galaxio-cli.git
cd galaxio-cli
go build -o bin/galaxio ./cmd/galaxio
go test ./...

Contributing

Two guards protect release tags. Both call scripts/check-linkage.sh, which holds the issue ↔ PR ↔ milestone rules; the same script runs on every pull request as the linkage CI job.

• Enable the release-tag hook once per clone. Without it .githooks/pre-push never runs. The linkage CI job validates a PR before it reaches main; this is the local fast failure for an exceptional manual tag.

  git config core.hooksPath .githooks
  

• Skipping the guard deliberately. A release step that must proceed while its milestone is still being closed is run as LINKAGE_OFF=1 <command>. That is the only sanctioned bypass: a command is never rephrased to get past the guard. A block names the version and the rule that failed, so fix the milestone rather than the wording.

License

galaxio-cli is licensed under the GNU General Public License, version 2 only (GPL-2.0-only); see LICENSE.

The public parsec result-primitives library is separately licensed under MIT. The reviewed MIT-to-GPL relationship is compatible for this planned dependency, but it is not a whole-module licence audit. See the naming and licence decision record for the compatibility rationale and its scope.