Manual for command line interface
The CLI is for more advanced use cases where you want more control over the validation or if you want to include the validation in your own pipeline. An example could be to recieve a file via an integration, validate the file with GreenLight and if there are any errors inform via email and otherwise save the file for use in another system.
To use the CLI you must first download the Docker image as described in Getting started
When you use the CLI you first give the command docker and the parameters run -it [docker_image] in this case the docker_image is itxpt/greenlight. After that you give the different commands and flags to greenlight, e.g., help. If you want to use other docker parameters, you have to put them before the name of the image to use. See below for more complex examples of how to invoke the greenlight command.
The tool has a built in help system that gives explanations of all commands and parameters in the tool. Use the command below to get an overview of the help you can get.
docker run -it itxpt/greenlight help
docker run -it -p 8080:8080 itxpt/greenlight server
This will start the built in web interface and it can be accessed via http://localhost:8080/. Se Web Interface for a guide on how to use it.
A validation is started with the command Validate, it uses the following flags as input to configure the validation.
Flags:
-h, --help help for validate
-i, --input string XML file, dir or archive to validate
-l, --log-level string Set level of log output (one of "trace", "debug", "info", "warn", "error") (default "debug")
-o, --output string Set which output format to use (one of "json", "xml", "csv", "pretty" (default "pretty")
-p, --profile string Set path of validation profile (note: flags 'rules' and 'schema' is ignored)
-r, --rules strings Set which validation rules to run (defaults to all inside the builtin dir)
-s, --schema string Which xsd schema to use (supported "netex@1.2", "netex@1.2-nc", "epip@1.1.2", "epip@1.1.2-nc") (default "netex@1.2-nc")
--silent Running in silent will only output the result in a boolean fashion
To verify that the tool works yo can do a validation with a NeTEx file provided with the tool.
docker run -it itxpt/greenlight validate -i testdata
Example output from a validation done in the CLI
To select NeTEx profile use the flag -s or --schema and the name of the profile. Valid names are netex@1.2, netex@1.2-nc, epip@1.1.2, epip@1.1.2-nc. If no schema is selected the netex@1.2-nc is used. -nc at the end means that the validation is with No Constraints. Which is a faster validation but needs that the no-constraints rule is used instead.
Example of how to use the EPIP schema when validating the built in test file
docker run -it itxpt/greenlight validate -schema epip@1.1.2 -i testdata
Select which rules to use with the flag -r or --rules and then give the name of the rules to use. Several rules can be specified by separating them with a comma.
Example -r everyLineIsReferenced,everyScheduledStopPointHasAName
You can change or add your own rules by cloning the greenlight repo from GitHub and modify one of the scripts in the directory builtin. Save it with a new name and then map the builtin folder to the docker container with the Docker parameter -v.
-v c:\code\greenlight\builtin:/usr/local/greenlight/builtin
Use the script in the same way as one of the standard scripts with the flag -r and name of the script.
Example -r mymodifiedrule
The files to test can be single files, a folder with files or a compressed archive with files. Put the files to be tested in a local folder and use the docker parameter -v to map it with a folder in the greenlight container.
-v C:\code\netex\testdata:/usr/local/greenlight/testdata
Then you can use the greenlight flag -i to include the files in the validation
Command to validate a folder with files
docker run -it -v c:\code\netex\testfiles:/usr/local/greenlight/testdata itxpt/greenlight validate -s netex@1.2-nc -r everyLineIsReferenced -i testdata
Command to validate an archive with several files
docker run -it -v c:\code\netex\testfiles:/usr/local/greenlight/testdata itxpt/greenlight validate -s netex@1.2-nc -r everyLineIsReferenced -i testdata/xt_2023_04_15.zip
Command to validate a single file
docker run -it -v c:\code\netex\testfiles:/usr/local/greenlight/testdata itxpt/greenlight validate -s netex@1.2-nc -r everyLineIsReferenced -i testdata/line_2_9011005000200000.xml
The result of the validation can be presented in different formats. For example, the pretty will give an output adopted to be read on the screen. The other formats json, xml and csv can be used to pipe the output to a file for further processing.
docker run -it itxpt/greenlight validate -s netex@1.2-nc -r everyLineIsReferenced -i testdata -o json > greenlight-result.json
Generate an autocompletion script for Greenlight for different shells. The generated script can be added to your shell profile. Scripts can be generated for bash, fish, zsh and powershell.
Note: This command is for power users who uses the CLI a lot and want to make it easier and faster to type commands and parameters.
As an example, will the command below generate a script for bash
docker run -it itxpt/greenlight completion bash