# `gelx_cli`

<br />

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

<br />

[![Crate][crate-image]][crate-link] [![Docs][docs-image]][docs-link] [![Status][ci-status-image]][ci-status-link] [![Unlicense][unlicense-image]][unlicense-link] [![codecov][codecov-image]][codecov-link]

## 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`:

```bash
cargo install gelx_cli
```

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

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

The above two commands are the typical ways to install `gelx_cli`. However, if you use `gel` in multiple projects with multiple versions of the `gelx` crate, you should install it locally per project using [`cargo-run-bin`](https://crates.io/crates/cargo-run-bin).

First install `cargo-run-bin`:

```bash
cargo install cargo-run-bin
```

Inside a single crate project add the following to the `Cargo.toml` file:

```toml
[package.metadata.bin]
gelx_cli = { version = "0.8.2", bins = ["gelx"] }
```

Inside a workspace add the following to the `Cargo.toml` file:

```toml
[workspace.metadata.bin]
gelx_cli = { version = "0.8.2", bins = ["gelx"] }
```

Then run the following command to access gelx:

```bash
cargo bin gelx
```

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

Run `gelx help` to see the available commands and options.

```bash
Generate fully typed rust code from your gel schema and inline queries.

Usage: gelx [OPTIONS] <COMMAND>

Commands:
  generate  Generates Rust code from the crate in the current directory
  check     Checks if the generated Rust code is up-to-date
  help      Print this message or the help of the given subcommand(s)

Options:
      --cwd <CWD>  Optional working directory to run the command from
  -h, --help       Print help
  -V, --version    Print version
```

## 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`

```bash
Generates Rust code from the crate in the current directory

Usage: gelx generate [OPTIONS]

Options:
      --json       Print the generated code as JSON to stdout instead of writing to a file
      --cwd <CWD>  Optional working directory to run the command from
  -h, --help       Print help
```

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

```bash
gelx generate --cwd path/to/your/crate
```

Or run the command with the `--json` flag to print the generated code to the terminal as JSON:

```bash
gelx generate --cwd path/to/your/crate --json
```

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.
- If `--json` is used, print the combined code to the terminal as JSON.
- Otherwise, write the combined code to the folder specified by `output_path` (default: `./src/db`).

#### `gelx check`

```bash
Checks if the generated Rust code is up-to-date

Usage: gelx check [OPTIONS]

Options:
      --cwd <CWD>  Optional working directory to run the command from
  -h, --help       Print help
```

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.

```bash
gelx check --cwd path/to/your/crate
```

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.

Refer to the main `gelx` crate [readme.md](https://github.com/ifiokjr/gelx/blob/main/readme.md#configuration) for all the configuration options.

## Contributing

This crate is part of the `gelx` workspace. Please refer to the [main project's contributing guide](https://github.com/ifiokjr/gelx/blob/main/CONTRIBUTING.md) for details on how to set up the development environment and contribute.

## License

Unlicense, see the [license file](https://github.com/ifiokjr/gelx/blob/main/LICENSE) in the root of the workspace.

[crate-image]: https://img.shields.io/crates/v/gelx_cli.svg
[crate-link]: https://crates.io/crates/gelx_cli
[docs-image]: https://docs.rs/gelx_cli/badge.svg
[docs-link]: https://docs.rs/gelx_cli/
[ci-status-image]: https://github.com/ifiokjr/gelx/workflows/ci/badge.svg?branch=main
[ci-status-link]: https://github.com/ifiokjr/gelx/actions?query=workflow%3Aci+branch%3Amain
[unlicense-image]: https://img.shields.io/badge/license-Unlicense-blue.svg
[unlicense-link]: https://github.com/ifiokjr/gelx/blob/main/LICENSE
[codecov-image]: https://codecov.io/github/ifiokjr/gelx/graph/badge.svg?token=87K799Q78I
[codecov-link]: https://codecov.io/github/ifiokjr/gelx
