> ## Documentation Index
> Fetch the complete documentation index at: https://docs.siftstack.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Generate a client with Buf

With [Buf](https://buf.build/docs/cli/), using a simple and declarative configuration, you can compile Protocol Buffers into language-specific source code, including gRPC client stubs. This approach is beneficial when working with Sift’s gRPC API, where the Protocol Buffers define the data structures and the service interfaces needed to generate a client.

**Sift provides official gRPC client libraries for Python, Rust, and Go.** If your preferred language is not one of these, such as TypeScript, Java, or C#, you can compile Sift’s Protocol Buffers using Buf to generate a compatible client library in that language.

<Info>
  Although there are several ways to compile Protocol Buffers, this guide focuses on using Buf because of its ease of use, flexible plugin system, and support for multiple programming languages.
</Info>

## Instructions

To compile Sift's Protocol Buffers using Buf, consider the following steps:

<Info>
  These steps (example) use Python as the target language, but you can adapt the process to other languages by selecting different plugins.
</Info>

1. Create a new directory for your Python client, and navigate into it. This directory will hold your Buf configuration and the generated client code.

   ```bash theme={null}
   mkdir sift-grpc-python-client
   cd sift-grpc-python-client
   ```

2. Install the Buf CLI globally by following the instructions in the [Buf installation instructions](https://buf.build/docs/installation/).

3. Clone the [Sift GitHub repository](https://github.com/sift-stack/sift) to access the Protocol Buffer definitions locally. These files define the gRPC services and messages that will be compiled into your Python client.

   ```bash theme={null}
   git clone https://github.com/sift-stack/sift.git
   ```

   <Info>
     The `.proto` files are located in the [protos subdirectory](https://github.com/sift-stack/sift/tree/main/protos) of the repository.
   </Info>

4. In your `sift-python-grpc-client` directory, create a file named `buf.gen.yaml`. This file specifies the plugins that Buf should use and where the generated code should be written.

   ```bash theme={null}
   nano buf.gen.yaml
   ```

   ```yaml theme={null}
   version: v1
   managed:
     enabled: true
   plugins:
     - plugin: buf.build/grpc/python:v1.62.1
       out: gen
     - plugin: buf.build/protocolbuffers/python
       out: gen
     - plugin: buf.build/protocolbuffers/pyi:v26.1
       out: gen
   ```

   This configuration generates Python message classes, gRPC client and server stubs, and type hint files. All output is written to the `gen/` directory by default, but you can modify the `out` paths to change the output location.

   <Info>
     Many of these plugins may require additional runtime dependencies after the code has been generated to work properly. Visit the documentation for each plugin you use to learn what packages or libraries must be installed.
   </Info>

5. From inside the `sift-python-grpc-client` directory, run the following command to export the `.proto` files from the Sift repository into a local directory:

   ```bash theme={null}
   buf export sift/protos --output=<OUTPUT_DIR> --config <PATH_TO_SIFT_BUF_CONFIG>
   ```

   * `<OUTPUT_DIR>` is the path to the directory where the Protocol Buffer files will be emitted. For example, `sift_protos`.
   * `<PATH_TO_SIFT_BUF_CONFIG>` is the path to the [`buf.yaml`](https://github.com/sift-stack/sift/blob/main/protos/buf.yaml) file located in the protos subdirectory of the cloned Sift repository (`sift`).

   ```bash theme={null}
   buf export sift/protos --output=sift_protos --config sift/protos/buf.yaml
   ```

   After running the command, verify that the `.proto` files were successfully copied into the `sift_protos` directory.

6. In the `buf.gen.yaml` file directory, run the following command to generate code from the `.proto` files you exported:

   ```bash theme={null}
   buf generate <OUTPUT_DIR>
   ```

   Replace `<OUTPUT_DIR>` with the name of the directory containing Sift's Protocol Buffers. For example, if you used `sift_protos`, the command would be:

   ```bash theme={null}
   buf generate sift_protos
   ```

   If the command runs successfully, the generated code will be written to the location specified in the out fields of your `buf.gen.yaml` file, such as the `gen/` directory.