gelx_cli

A command-line interface for gelx to generate fully typed Rust code from your Gel schema and query files.

Installation

The gelx_cli is distributed as part of the gelx workspace. To use it, you can build the workspace and then run the gelx binary from the target directory, or install it using cargo:

cargo install gelx_cli

Alternatively, you can install it directly from the github repo:

cargo install --git https://github.com/ifiokjr/gelx.git gelx_cli

Ensure your Gel instance is running and accessible, as the CLI needs to connect to it to introspect the schema and query types.

Global Options

• --cwd <path>: Specifies a working directory to run the command from. If provided, gelx will change to this directory before performing any operations. This is useful if you are invoking gelx from a directory different from your project's root.

Usage

The gelx CLI tool generates Rust code from .edgeql files located in your project. It reads configuration from your crate's Cargo.toml file, specifically under the [package.metadata.gelx] section.

Commands

gelx generate

This command generates Rust code based on your .edgeql query files and the Gel schema.

1. Navigate to your crate's root directory:

   cd path/to/your/crate
   

2. Run the generate command:

   gelx generate
   

   The CLI will:

   • Read configuration from [package.metadata.gelx] in your Cargo.toml.
   • Scan the directory specified by queries (default: ./queries) for .edgeql files.
   • Connect to your Gel instance to get type information for each query.
   • Generate corresponding Rust modules.
   • Write the combined code to the file specified by output_file (default: ./src/gelx_generated.rs).

gelx check

This command verifies if the currently generated code is up-to-date with your schema and query files. It's useful for CI pipelines to ensure that code generation has been run after any changes.

1. Navigate to your crate's root directory:

   cd path/to/your/crate
   

2. Run the check command:

   gelx check
   

   The CLI will:

   • Perform the same generation process as gelx generate in memory.
   • Compare the newly generated code with the content of the existing output_file.
   • If they match, it will exit successfully (status code 0).
   • If they differ, it will print an error message and exit with a non-zero status code, indicating that gelx generate needs to be run.

Configuration

The gelx CLI reads its configuration from the Cargo.toml file of the crate it is being run in. The configuration should be placed under the [package.metadata.gelx] table.

Example Cargo.toml configuration:

[package.metadata.gelx]
## The location of the queries relative to the root of the crate.
queries = "./queries"

## The features to enable and their aliases. By default all features are enabled.
## To disable a feature set it to false. The available features are:
## - query
## - serde
## - strum
## - builder
features = { query = "ssr", strum = "ssr", builder = "ssr" }

## The location of the generated code when using the `gelx` cli.
output_file = "./src/gelx_generated.rs"

## The name of the arguments input struct. Will be transformed to PascalCase.
input_struct_name = "Input"

## The name of the exported output struct for generated queries. Will be transformed to PascalCase.
output_struct_name = "Output"

## The name of the query function exported.
query_function_name = "query"

## The name of the transaction function exported.
transaction_function_name = "transaction"

## The relative path to the `gel` config file. This is optional and if not provided the `gel`
## config will be read from the environment variables.
# gel_config_path = "./gel.toml"

## The name of the `gel` instance to use. This is optional and if not provided the environment
## variable `$GEL_INSTANCE` will be used.
# gel_instance = "$GEL_INSTANCE"

## The name of the `gel` branch to use. This is optional and if not provided the environment
## variable `$GEL_BRANCH` will be used.
# gel_branch = "$GEL_BRANCH"

Refer to the main gelx crate readme.md for more details on the core library and its features.

Contributing

This crate is part of the gelx workspace. Please refer to the main project's contributing guide for details on how to set up the development environment and contribute.

License

Unlicense, see the license file in the root of the workspace.