celq

celq is a command-line tool for evaluating Common Expression Language (CEL) expressions. It processes JSON input, performs computations, and outputs results. Think of it as if jq supported CEL.

Quick Start

celq reads JSON from the input and lets users process it with CEL:

echo '["apples", "bananas", "blueberry"]' | celq 'this.filter(s, s.contains("a"))'
# Outputs: ["apples","bananas"]

celq can also evaluate expressions with arguments, without reading from the input:

celq -n --arg='fruit:string=apple' 'fruit.contains("a")'
# Outputs: true

Closely related formats such as NDJSON and JSON5 are also supported.

For detailed usage examples and recipes, see the manual.

Why?

There are implementations of CEL for Go, C++, Python, JavaScript, Rust, and possibly more languages.

celq brings the same CEL syntax to the command-line. celq is not necessarily better than jq, but perhaps it makes it easier to reuse snippets of code accross multiple places.

Moreover, the CEL specification is simpler than the jqlang specification. If you need something less powerful than jq or Python, then celq might be what you are looking for.

Installation

Pre-built Binaries

We publish pre-built binaries in celq's GitHub Releases page.

Homebrew (macOS)

If you are a macOS Homebrew user, then you can install celq with:

brew install IvanIsCoding/tap/celq

Installing From Source

If you want to install from source, celq publishes to crates.io.

cargo install celq

Installing With cargo-binstall

If you have cargo-binstall installed, you can install pre-built binaries directly:

cargo binstall celq

Python

celq is packaged for PyPI. Python users can install it with pip:

pip install celq

If you have uv installed, celq can be used as a tool:

uvx celq -n '"Hello World"'

NPM (Node.js/JavaScript)

Node.js users can install celq in their project with:

npm install celq

This adds celq to package.json and makes it available for scripts. It's also possible to run single commands with:

npx celq -n '"Hello World"'

Limitations

CEL Implementation Differences

celq uses cel-rust, a community-maintained Rust implementation of CEL, rather than the official Go implementation.

While cel-rust provides excellent compatibility with the CEL specification, there may be edge cases or advanced features where behavior differs from the official implementation. If you find one, feel free to report it at their repository.

JSON Parsing

celq eagerly parses all JSON input into memory before evaluation. This design was made to simplify the code implementation, at the cost of memory and performance.

Currently, there are no benchmarks for celq. I believe the tool is "good enough" for my personal use. That might be revisited in the future. In the meantime, expect celq to be slower than jq.

List and Map Arguments

Currently, the --arg syntax only supports int, bool, float, and string. Support for other CEL types will be added in the future.

Non-Goals

REPL

While conceptually interesting, celq does not aim to be a CEL REPL. In the original author's view, that should live on a separate binary.

YAML Support

celq works with JSON. I originally considered supporting YAML as a supported input format. However, the amount of YAML edge cases pushed me back to JSON. Although that might change in the future, please do not open an issue asking for YAML support as of today.

Acknowledgments

Special thanks to the maintainers of:

• cel-rust for providing the CEL evaluation engine that powers celq
• cel-python for publishing their CLI. celq has heavily drawn from their interface
• jaq for giving an excellent blueprint on how to test a Rust CLI

Large Language Models Disclosure

Many commits in this repository were co-authored by LLMs. All commits were guided and reviewed by a human. The original author has significantly refactored the AI output to conform to his opinionated view.

All the documentation in the manual has been hand-crafted. That was done to keep the tone of the original author. If you find a typo or a grammar mistake, please send a pull request.

License

This project is dual-licensed under the MIT License and Apache 2.0 licenses. See LICENSE-MIT and LICENSE-APACHE file for details.

Contributing

Contributions are welcome! See CONTRIBUTING.md for more details.