> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://beta-docs.payabli.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://beta-docs.payabli.com/_mcp/server.

# Query CLI app

The Payabli Query CLI application is a command-line tool that allows you to run queries against your Payabli data.
It supports all of Payabli's query APIs and provides a flexible way to retrieve and analyze your data.
The app also supports special clauses to help you adjust your queries and can save multiple configurations for different environments.

Visit the [repository](https://github.com/payabli/payquery-cli/) to see the code.

> **Note**
>
> Once you have the application installed, we recommend you add the application [to your PATH](#optional%3A-add-the-app-to-your-path) for easy access.

## Dependencies

Before you begin, make sure you have the following installed on your machine:

* [cargo](https://doc.rust-lang.org/cargo/getting-started/installation.html)
* [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)

## Manual setup

Run these commands in your terminal to install the query CLI app on your local machine:

#### Clone the repo

```
git clone https://github.com/payabli/payquery-cli
```

#### Compile the application

```
cargo build --release
```

#### Make a default config

```
cargo run
```

Follow the prompts and enter your Payabli API information to create a default config.

#### Run a query

```
cargo run -- transactions
```

## Optional: Add the app to your PATH

If you want to run the query CLI app from anywhere on your machine, you can add it to your PATH.
This allows you to run the application as `payquery` from any directory, instead of navigating to the application directory and running `cargo run`.

#### Install the application

```
cargo install --path .
```

#### Add the binary to your PATH

```
export PATH=$PATH:~/.cargo/bin
```

#### Run the app from anywhere

```
payquery chargebacks 
```

> **Note**
>
> You can also manually place the binary in a directory that is already in your PATH.

## Usage

The Payabli Query CLI application supports all of Payabli's query APIs.
To run a query, put the name of the API endpoint after the `payquery` command.

```shell
payquery payouts
```

### Clauses

The application supports special clauses to help you adjust your queries to be more helpful and precise.

* **`only N ...`**: Limit the number of records to N (comes before the API endpoint).
* **`... for NAME`**: Use the configuration named NAME.
* **`... where FILTERS`**: Filter records based on the given conditions.
* **`... by FIELD`**: Sort records by FIELD in ascending order.
* **`... by FIELD desc`**: Sort records by FIELD in descending order.
* **`... crop`**: Output only the sorted field values (must come after a BY clause).

> **Note**
>
> The `for` clause uses the [query parameters](/api-reference/query/get-list-of-transactions-for-an-entrypoint#parameter-parameters) for the API endpoint.
> The `by` clause uses the field names of the [response object](/api-reference/query/get-list-of-transactions-for-an-entrypoint#response-records) for the API endpoint.

To retrieve only 5 transactions where the transaction date is after the beginning of this week, run:

```shell
payquery only 5 transactions where transactionDate gt this week
```

To retrieve all chargebacks where the net amount is less than \$100.00, and then sort those chargebacks by reply date, run:

```shell
payquery chargebacks where netAmount lt 100 by ReplyBy 
```

To see a list of all payment methods used in transactions by customers with the first name "John", run:

```shell
payquery transactions where customerFirstname eq John by Method crop
```

To retrieve all customers for the configuration named `sandbox`, run:

```shell
payquery customers for sandbox
```

> **Note**
>
> Configurations are stored in a YAML file located in your home directory as `payquery.yml`.
> Each configuration contains an API token, organization ID, entrypoint ID, and environment (sandbox or production).

### Subcommands

The Payabli Query CLI application also supports the following subcommands:

* **`new`**: Create a new configuration.
* **`list`**: List all available configurations.
* **`help`**: Show this help message.

To create a new configuration, run:

```shell
payquery new
```

To list all available configurations, run:

```shell
payquery list
```

To see the help message, run:

```shell
payquery help
```

### Options

Finally, the Payabli Query CLI application supports the following options that must be provided at the beginning of the command:

* **`--json`**: Output in JSON format (default).
* **`--yaml`**: Output in YAML format.
* **`--quiet`**: Don't output information besides the query result.

To output the query result in YAML format, run:

```shell
payquery --yaml batches 
```

To output the query result in JSON format, run:

```shell
payquery --json batches 
```

To output only the query result without any additional information, run:

```shell
payquery --quiet batches 
```

> **Note**
>
> If you are writing a script that uses the query CLI app, you can use the `--quiet` option to get only the query result without any response status information.
> This can be useful if you want to parse the query result in your script or use the query result as input for another command.