Cyphernetes: a Cypher-style query language for Kubernetes

The problem is the shell pipeline, not the API

The example the project leads with is a familiar one. Deleting every pod that is not running takes a kubectl invocation with a field selector, a custom-columns output format, a pipe to xargs, and a nested shell command to split the namespace from the name. It works, and nobody enjoys reading it.

Cyphernetes expresses the same intent as a query:

MATCH (p:Pod)
WHERE p.status.phase != "Running"
DELETE p;

That is the whole pitch. The language is described as Cypher-inspired, a mixture of ASCII art, SQL and JSONPath, and it exists so that Kubernetes graph operations can be written in a way that reads like a question about a graph rather than a pipeline of shell commands.

The interesting part is not the syntax but what the engine knows. The project states that the relationships between Kubernetes resource kinds are the tool's superpower, expressed with the arrow syntax, so that connected operations can be written naturally without worrying about the underlying Kubernetes API. The README shows it with `MATCH (d:Deployment {name: "nginx"})` followed by `CREATE (d)->(s:Service)`, which the documentation compares to `kubectl expose`.

The audience is a cluster operator or platform engineer, someone who already knows the Kubernetes object model and wants a better way to interrogate it, especially one who is tired of writing the same multi-line kubectl pipeline for the fifteenth time.

The engine sits between a parser and a provider interface

The repository layout shows the architecture more clearly than the feature list does. It is a monorepo with several packages, and the directory tree in the project documentation is worth reading closely.

The `pkg/core` directory holds the core Cyphernetes package, described as the parser and engine behind the language features. The `pkg/provider` directory holds an interface for different backend implementations, and inside it the `apiserver` package is a client for the Kubernetes API server. The `cmd/cyphernetes` directory is the CLI where the binary lives, `web/src` is the web client, `operator/` is the operator, and `docs/` is the cyphernet.es website.

So the shape is a parser and engine that knows the language, sitting on top of a provider abstraction, with the Kubernetes implementation of that abstraction being a client for the API server. That provider seam is what makes the multi-cluster support and the CRD support possible in principle, because a query does not have to assume one fixed endpoint.

The Go module confirms the toolchain. The module is `github.com/avitaltamir/cyphernetes` on Go 1.24.0, with cobra for the command line, gin for the web server, controller-runtime and the API extension machinery for the operator, and the Kubernetes client libraries. It also depends on a custom JSONPath module, `github.com/AvitalTamir/jsonpath`, which is a fork rather than the upstream package.

Six ways to run a query, and they are not equivalent

The project documentation lists six ways to run Cyphernetes, and the differences between them matter more than the list suggests.

The web client is started from your terminal with `cyphernetes web` and then visited at `http://localhost:8080`. The interactive shell is `cyphernetes shell` in the terminal. A single query can be run with `cyphernetes query "your query"`, which the documentation points at as the option for scripting and CI/CD pipelines. The `kubectl cypher` plugin installs via Krew or from the latest release, which puts the language inside the tool most Kubernetes users already have open. A Cyphernetes DynamicOperator can be created using the cyphernetes-operator to define Kubernetes workflows on the fly, and the Cyphernetes API can be used directly from your own Go programs.

The DynamicOperator is the most interesting of the six and. It is a CRD-based mechanism for turning a query into a workflow that runs inside the cluster, which moves the language from an interactive tool to a declarative object you can apply with kubectl.

For a scripting use case the `cyphernetes query` form is the one that matters, since it composes with a shell pipeline and returns JSON. The example output in the documentation is JSON, one object per returned row, followed by the query execution time in milliseconds.

Installing the binary three ways

Getting the tool is straightforward, and there are three documented routes.

Homebrew is the shortest:

brew install cyphernetes

If you already have Go, the module path is the way in:

go install github.com/avitaltamir/cyphernetes/cmd/cyphernetes@latest

And the third option is to download a binary directly from the releases page.

The same binary serves all three commands, since `web`, `shell` and `query` are subcommands of `cyphernetes`. The kubectl plugin is a separate binary named `kubectl-cypher`, which the Makefile builds with a `build-kubectl-plugin` target and which can be installed through Krew.

The build itself is a Makefile affair, and the default target is worth noting. Running `make` builds the operator manifests and the web client static assets, then builds the binary and runs the tests, so a full build pulls in Node and pnpm as well as Go. There are separate targets for the pieces, `make web-build` and `make operator-build`, for when you only need one of them.

The documented prerequisites for development are Go (latest), Make, NodeJS (latest) and pnpm 9 or newer, and the Makefile also carries a coverage floor of 80.0 for the core package.

Building from source needs Go, Node and pnpm together

The development setup is where the monorepo shows its cost. The repository layout has four buildable pieces, the Go CLI and core, the web client under `web/src`, the operator, and the documentation site under `docs/`, and the web client and the operator are built with tooling that has nothing to do with Go.

The setup sequence in the documentation is clone, then change directory, then build:

git clone https://github.com/avitaltamir/cyphernetes.git
cd cyphernetes
make

The individual build targets are:

make web-build
make operator-build

The Makefile also cross-compiles. There is a `build-all-platforms` target that loops over darwin, linux and windows with amd64 and arm64, producing binaries named for the platform, and a matching target for the kubectl plugin. The version string is injected at link time with `-ldflags "-X main.Version=${VERSION}"`, defaulting to `dev`, which is how a locally built binary is distinguishable from a released one.

A developer who only wants to work on the parser and the engine in `pkg/core` still needs the whole toolchain, because the default target builds the web client before the binary. The `test` target runs against the core package, and the coverage minimum of 80.0 is enforced for it.

CRDs work, and that is where the risk lives

The project states that Cyphernetes works out of the box with your CRDs and supports multi-cluster queries. That first claim is what separates it from a shell pipeline, since a custom resource has no fields you can guess from the built-in API.

The risk is the same one that comes with any tool that can express a delete. The language allows a `DELETE` over a matched set, and a match can be broad. The example query deletes every pod that is not running across all namespaces, which is a reasonable operation in a development cluster and a serious one in a production cluster shared with other teams.

The failure mode to watch for is a query that matches more than intended, and the way to manage that is the way you manage any cluster tool, by checking the match before you act. The language separates the two steps, since a `MATCH` with a `RETURN` shows you what would be selected, and that is the habit worth forming.

The operator route deserves particular care. A DynamicOperator turns a query into an object that the cluster reconciles, which means a badly written query can keep acting rather than acting once. That is a different risk profile from running the same query by hand, and it is the reason to read the operator samples in the repository before creating one in a cluster that matters.

Maintenance has been quiet since mid-2025

The version history is worth reading carefully, because it shows two different timelines. The most recent release tags are v0.18.0 on 2025-06-27, v0.18.1 on 2025-06-28 and v0.18.2 on 2025-06-29, a cluster of patch releases in three days. The repository itself is not archived, and the last push was on 2026-07-03, so commits have continued to land in the tree well after the last tag.

The gap between a tag from June 2025 and commits in July 2026 is the signal here. Work is happening, but the release cadence has not produced a new tagged version in that window, so anyone installing with `brew install cyphernetes` or the `go install...@latest` path gets whatever the current published artefact is, and the main branch may be ahead of it. The releases page is the place to check what is actually published.

The project is licensed under Apache 2.0, as the README states and the LICENSE file in the repository root holds. For a tool that talks to a cluster, the practical licence point is the patent grant and the requirement to preserve notices, which matters if you redistribute the binary inside an internal image.

The project is maintained by a named maintainer, Naor Peled, with the initial work by AvitalTamir and a list of contributors, and the acknowledgements credit Neo4j for the Cypher inspiration and two graph rendering projects for the ASCII art server.

Editorial conclusion

Cyphernetes fits an operator who writes cluster queries by hand or scripts them in CI, and who wants the relationships between resource kinds to be part of the query language rather than something to remember. It is the wrong tool for a GitOps pipeline where the manifests are the source of truth, and it will not replace a controller for anything that has to react to events. Check first that your cluster credentials and RBAC allow the kinds you intend to query, then try the same operation with `cyphernetes query` and with plain kubectl before you turn a MATCH into a DELETE in a shared cluster.

Frequently asked questions

Official sources

1. AvitalTamir/cyphernetes on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases