This repository is home to the ion
command line tool, which provides subcommands
for working with the Ion data format.
These examples use the .ion
file extension for text Ion and the .10n
file
extension for binary Ion. This is simply a convention; the tool does not
evaluate the file extension.
Unless otherwise noted, these commands can accept any Ion format as input.
The ion cat
command reads the contents of the specified files (or STDIN
) sequentially
and writes their content to STDOUT
in the requested Ion format.
ion cat my_file.ion
You can use the --format
/-f
flag to specify the desired format. The supported formats are:
pretty
- Generously spaced, human-friendly text Ion. This is the default.text
- Minimally spaced text Ion.lines
- Text Ion that places each value on its own line.binary
- Binary Ion
Convert Ion text (or JSON) to Ion binary:
ion cat --format binary my_text_file.ion -o my_binary_file.ion
Convert Ion binary to generously-spaced, human-friendly text:
ion cat --format pretty my_binary_file.ion -o my_text_file.ion
Convert Ion binary to minimally-spaced, compact text:
ion cat --format text my_binary_file.ion -o my_text_file.ion
The to
and from
commands can convert Ion to and from other formats.
Currently, JSON is supported.
Convert Ion to JSON:
ion to -X json my_file.10n
Convert JSON to Ion:
ion from -X json my_file.json
The inspect
command can display the hex bytes of a binary Ion file alongside
the equivalent text Ion for easier analysis.
# Write some text Ion to a file
echo '{foo: null, bar: true, baz: [1, 2, 3]}' > my_file.ion
# Convert the text Ion to binary Ion
ion cat --format binary my_file.ion > my_file.10n
# Show the binary encoding alongside its equivalent text
ion inspect my_file.10n
The --skip-bytes
flag
To skip to a particular offset in the stream, you can use the --skip-bytes
flag.
ion inspect --skip-bytes 30 my_file.10n
Notice that the text column adds comments indicating where data has been skipped. Also, if the requested index is nested inside one or more containers, the beginnings of those containers (along with their lengths and offsets) will still be included in the output.
The --limit-bytes
flag
You can limit the amount of data that inspect
displays by using the --limit-bytes
flag:
ion inspect --skip-bytes 30 --limit-bytes 2 my_file.10n
All the subcommand to load or validate schema are under the schema
subcommand.
To load a schema:
ion schema -X load --directory <DIRECTORY> --schema <SCHEMA_FILE>
To validate an ion value against a schema type:
ion schema -X validate --directory <DIRECTORY> --schema <SCHEMA_FILE> --input <INPUT_FILE> --type <TYPE>
For more information on how to use the schema subcommands using CLI, run the following command:
ion schema help
The easiest way to install the ion-cli
is via Homebrew.
Once the brew
command is available, run:
brew tap amazon-ion/ion-cli
brew install ion-cli
The ion-cli
can also be installed by using Rust's package manager, cargo
.
If you don't already have cargo
, you can install it by visiting
rustup.rs.
To install ion-cli
, run the following command:
cargo install ion-cli
If you are looking into accessing all features with brew
(including experimental
features, currently only
includes generate
subcommand) of ion-cli
, run:
brew install ion-cli --HEAD
If you are looking into accessing all features with cargo
(including experimental
features) of ion-cli
, run:
cargo install ion-cli --all-features
Then make sure that ~/.cargo/bin
is on your $PATH
. You can confirm that it
has been installed successfully by running:
ion help
You should see output that resembles the following:
A collection of tools for working with Ion data.
Usage: ion [OPTIONS] <COMMAND>
Commands:
cat Prints all Ion input files to the specified output in the requested format.
count (UNSTABLE) Prints the number of top-level values found in the input stream.
from 'from' is a namespace for commands that convert other data formats to Ion.
generate (UNSTABLE) Generates code using given schema file.
head Prints the specified number of top-level values in the input stream.
inspect Displays hex-encoded binary Ion alongside its equivalent text Ion.
Its output prioritizes human readability and is likely to change
between versions. Stable output for programmatic use cases is a
non-goal.
primitive (UNSTABLE) Prints the binary representation of an Ion encoding primitive.
schema The 'schema' command is a namespace for commands that are related to Ion Schema.
symtab 'symtab' is a namespace for commands that operate on symbol tables
to 'to' is a namespace for commands that convert Ion to another data format.
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
-V, --version Print version
-X, --unstable Opt in to using an unstable feature of Ion CLI.
-
Clone the repository:
git clone https://github.com/amzn/ion-cli.git
-
Step into the newly created directory:
cd ion-cli
-
Install Rust/Cargo by visiting rustup.rs.
-
Build the
ion
tool:cargo install --path .
This will put a copy of the
ion
executable in~/.cargo/bin
. -
Confirm that
~/.cargo/bin
is on your$PATH
.rustup
will probably take care of this for you. -
Confirm that the executable is available by running:
ion help
- Install Docker (see OS specific instructions on the Docker website)
- Clone the repository (recursive clone not necessary)
git clone https://github.com/amzn/ion-cli.git
- Step into the newly created directory
cd ion-cli
- Build and run the image
# build the image docker build -t <IMAGE_NAME>:<TAG> . # run the CLI binary inside the Docker image docker run -it --rm [optional flags...] <IMAGE_NAME>:<TAG> ion <SUBCOMMAND> # examples: # build docker image with current release version docker build -t ion-cli:0.1.1 . # print the help message docker run -it --rm ion-cli:0.1.1 ion -V # mount current directory to /data volume and cat an ion file docker run -it --rm -v $PWD:/data ion-cli:0.1.1 ion cat /data/test.ion
See CONTRIBUTING for more information.
This project is licensed under the Apache-2.0 License.