jelly-cli

Fast and convenient CLI utility for working with the Jelly knowledge graph streaming protocol.

⚡ Quick start

Install script

If you are using Linux (x86_64, ARM64), macOS (ARM64), or WSL on Windows, the recommended way is to use the setup-cli.sh script, which will automatically install the newest release. To do so, run:

. <(curl -sSfL https://w3id.org/jelly/setup-cli.sh)
jelly-cli

mise

You can install jelly-cli on any platform (including Windows) using mise. Simply run:

mise use -g 'ubi:Jelly-RDF/cli[exe=jelly-cli]'
jelly-cli

Manual download

Alternatively, you can download the binary manually (this also works for Windows). Go to the releases page and download the build for your platform.

You can then run it like so:

chmod +x jelly-cli
./jelly-cli

Or, on Windows:

jelly-cli.exe

Usage

Convert RDF to Jelly

To convert an RDF file (e.g., Turtle) to Jelly, simply run:

jelly-cli rdf to-jelly input.ttl > output.jelly

Convert Jelly to RDF

To convert from Jelly to RDF run:

jelly-cli rdf from-jelly input.jelly > output.nq

By default, jelly-cli will translate files to NQuads. You can also specify the output format with --out-format, for example:

jelly-cli rdf from-jelly input.jelly --out-format=ttl > output.ttl

You can specify most well-known formats supported by Apache Jena, but also the custom jelly-text format. jelly-text is a human-readable translation of Jelly binary. It's not meant for machine consumption. It is useful for debugging and inspecting Jelly files.

Transcode Jelly files

The rdf transcode command turns one or more input Jelly streams into a single output stream. It's extremely fast, using a dedicated transcoding algorithm. This algorithm has a limitation: the lookup sizes of the output stream must be greater than or equal to the lookup sizes of the input streams.

jelly-cli rdf transcode input.jelly > output.jelly

Inspect Jelly files

To inspect a Jelly file and get basic information describing its contents, such as stream options or number of triples in the file, run:

jelly-cli rdf inspect input.jelly

You can also compute the statistics separately for each stream frame with the --per-frame option:

jelly-cli rdf inspect input.jelly --per-frame

In both cases, you will get the output as a valid YAML.

Validate Jelly files

To validate a Jelly file, run:

jelly-cli rdf validate input.jelly

You can also check whether the Jelly file has been encoded using specific stream options or is equivalent to another RDF file, with the use of additional options to this command.

Convert SPARQL results to and from Jelly-SPARQL

Jelly-SPARQL is a columnar format for SPARQL query results. To convert results to it, run:

jelly-cli sparql to-jelly results.srj > results.jellys

And to convert back:

jelly-cli sparql from-jelly results.jellys --out-format=csv > results.csv

Both commands handle SELECT results (bindings) and ASK results (a boolean). All standard result formats (JSON, XML, CSV and TSV) are supported, plus a plain text table (text) for output only.

Jelly-SPARQL is an experimental draft and the format may still change.

General tips

Use the --help option to learn more about all the available settings:

jelly-cli rdf to-jelly --help
jelly-cli rdf from-jelly --help
jelly-cli rdf transcode --help
jelly-cli rdf inspect --help
jelly-cli rdf validate --help
jelly-cli sparql to-jelly --help
jelly-cli sparql from-jelly --help

And use the --debug option to get more information about any exceptions you encounter.

Alternative installation: JAR builds

If for some reason the binaries wouldn't work for you, or you want to get better performance for large files (see Performance considerations below), you can use the JAR build. This build runs on any platform, as long as you have Java (min. version 21). Go to the releases page and download the jelly-cli.jar file. Then, run it like so:

java -jar jelly-cli.jar --help

For simple day-to-day use cases, we recommend using the binary distribution, because it has way faster startup times and doesn't require you to install Java.

Java version requirements

Depending on the version of jelly-cli:

• 0.10.x or later: Java 21+
• 0.1.x – 0.9.x: Java 17+

Performance considerations

If you are bulk-converting large amounts of RDF data (>10M triples), you may want to use the JAR build instead of the pre-compiled binary. With the JAR, your JVM will perform just-in-time compilation, resulting in better optimized code. The application will take longer to start, but the overall throughput will be better for large files.

For maximum performance, we recommend using a recent JVM (e.g., OpenJDK 25). In some cases we saw up to 2x better throughput when running the JAR with GraalVM 24 in JIT mode, as compared to the pre-compiled binary.

GitHub Action

If you're using jelly-cli in your GitHub Action CI/CD workflows, consider using the jelly-rdf/setup-cli action (Marketplace link). The action will automatically download and install the appropriate binary. Simply run the action before jelly-cli usage:

steps:
  - uses: Jelly-RDF/setup-cli@v1
    
  - run: jelly-cli rdf to-jelly input.ttl > output.jelly

RDF-star/RDF 1.2 compatibility

jelly-cli includes partial support for RDF 1.2 (triple terms only).

v0.10.0 is the last release that supported RDF-star. It is based on Jena 5.3.0, the last version of Jena to support RDF-star.

Contributing

We welcome contributions! Feel free to open an issue, suggest new features, or submit pull requests.

💬 Chat with us on Discord to ask questions or discuss ideas.

⭐ Consider starring this repository – this really helps the project!

Developer notes

Run sbt fixAll before committing. Your code should be formatted and free of warnings. The CI checks will not pass if this is not the case.

Building from source

Ahead-of-time compilation (single binary)

• Ensure you have GraalVM installed and the native-image utility is available in your PATH.
• Clone the repository.
• Run sbt GraalVMNativeImage/packageBin
• The binary will be available at ./target/out/jvm/scala-3.*.*/jelly-cli/graalvm-native-image/jelly-cli.

Über-JAR build (just-in-time)

• Run sbt assembly
• The resulting JAR will be in ./target/out/jvm/scala-3.*.*/jelly-cli/jelly-cli-assembly-*.jar
• Run it like: java -jar <path-to-jar>

---

The development of the Jelly protocol, its implementations, and supporting tooling was co-funded by the European Union. More details.