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.
Convert Ion text (or JSON) to Ion binary:
ion dump --format binary my_file.ionConvert Ion binary to generously-spaced, human-friendly text:
ion dump --format pretty my_file.10nConvert Ion binary to minimally-spaced, compact text:
ion dump --format text my_file.10nThe beta to and beta from commands can convert Ion to and from other formats.
Currently, JSON is supported.
Convert Ion to JSON:
ion beta to json my_file.10nConvert JSON to Ion:
ion beta from json my_file.jsonThe beta 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 dump --format binary my_file.ion > my_file.10n
# Show the binary encoding alongside its equivalent text
ion beta inspect my_file.10n
---------------------------------------------------------------------------
Offset | Length | Binary Ion | Text Ion
---------------------------------------------------------------------------
| 4 | e0 01 00 ea | // Ion 1.0 Version Marker
4 | 4 | ee 95 81 83 | '$ion_symbol_table':: // $3::
8 | 19 | de 91 | {
10 | 1 | 86 | 'imports': // $6:
11 | 2 | 71 03 | $ion_symbol_table, // $3
13 | 1 | 87 | 'symbols': // $7:
14 | 13 | bc | [
15 | 4 | 83 66 6f 6f | "foo",
19 | 4 | 83 62 61 72 | "bar",
23 | 4 | 83 62 61 7a | "baz",
| | | ],
| | | }
27 | 13 | dc | {
28 | 1 | 8a | 'foo': // $10:
29 | 1 | 0f | null,
30 | 1 | 8b | 'bar': // $11:
31 | 1 | 11 | true,
32 | 1 | 8c | 'baz': // $12:
33 | 7 | b6 | [
34 | 2 | 21 01 | 1,
36 | 2 | 21 02 | 2,
38 | 2 | 21 03 | 3,
| | | ],
| | | }To skip to a particular offset in the stream, you can use the --skip-bytes flag:
ion beta inspect --skip-bytes 30 my_file.10n
---------------------------------------------------------------------------
Offset | Length | Binary Ion | Text Ion
---------------------------------------------------------------------------
| 4 | e0 01 00 ea | // Ion 1.0 Version Marker
| | ... | // Skipped 23 bytes of user-level data
27 | 13 | dc | {
| | ... | // Skipped 2 bytes of user-level data
30 | 1 | 8b | 'bar': // $11:
31 | 1 | 11 | true,
32 | 1 | 8c | 'baz': // $12:
33 | 7 | b6 | [
34 | 2 | 21 01 | 1,
36 | 2 | 21 02 | 2,
38 | 2 | 21 03 | 3,
| | | ],
| | | }
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.
You can limit the amount of data that inspect displays by using the --limit-bytes
flag:
ion beta inspect --skip-bytes 30 --limit-bytes 2 my_file.10n
---------------------------------------------------------------------------
Offset | Length | Binary Ion | Text Ion
---------------------------------------------------------------------------
| 4 | e0 01 00 ea | // Ion 1.0 Version Marker
| | ... | // Skipped 23 bytes of user-level data
27 | 13 | dc | {
| | ... | // Skipped 2 bytes of user-level data
30 | 1 | 8b | 'bar': // $11:
31 | 1 | 11 | true,
| | ... | // --limit-bytes reached, stepping out.
| | | }All the subcommand to load or validate schema are under the beta schema subcommand.
To load a schema:
ion beta schema load --directory <DIRECTORY> --schema <SCHEMA_FILE> To validate an ion value against a schema type:
ion beta schema 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 beta 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-cliThe 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-cliThen make sure that ~/.cargo/bin is on your $PATH. You can confirm that it
has been installed successfully by running:
ion helpYou should see output that resembles the following:
ion 0.4.0
The Ion Team <[email protected]>
USAGE:
ion <SUBCOMMAND>
FLAGS:
-h, --help Prints help information
-V, --version Prints version information
SUBCOMMANDS:
beta The 'beta' command is a namespace for commands whose interfaces are
not yet stable.
dump Prints Ion in the requested format
help Prints this message or the help of the given subcommand(s)
-
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
iontool:cargo install --path .This will put a copy of the
ionexecutable in~/.cargo/bin. -
Confirm that
~/.cargo/binis on your$PATH.rustupwill 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 dump an ion file docker run -it --rm -v $PWD:/data ion-cli:0.1.1 ion dump /data/test.ion
See CONTRIBUTING for more information.
This project is licensed under the Apache-2.0 License.