ion-cliThis 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.
dumpConvert Ion text (or JSON) to Ion binary:
shell
ion dump --format binary my_file.ion
Convert Ion binary to generously-spaced, human-friendly text:
shell
ion dump --format pretty my_file.10n
Convert Ion binary to minimally-spaced, compact text:
shell
ion dump --format text my_file.10n
inspectThe beta inspect command can display the hex bytes of a binary Ion file alongside
the equivalent text Ion for easier analysis.
```shell
echo '{foo: null, bar: true, baz: [1, 2, 3]}' > my_file.ion
ion dump --format binary myfile.ion > myfile.10n
ion beta inspect my_file.10n
| 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:
```
| 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:
```shell
| 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.
| | | }
```
The ion-cli is written in Rust. The easiest way to install it on your machine is
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:
shell
cargo install ion-cli
Then make sure that ~/.cargo/bin is on your $PATH. You can confirm that it
has been installed successfully by running:
shell
ion help
You should see output that resembles the following:
``` ion 0.4.0 The Ion Team ion-team@amazon.com
USAGE:
ion
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 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
git clone https://github.com/amzn/ion-cli.git
cd ion-cli
Build and run the image ```
docker build -t
docker run -it --rm [optional flags...]
docker build -t ion-cli:0.1.1 .
docker run -it --rm ion-cli:0.1.1 ion -V
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.