Protodex

Overview
Protodex is a CLI tool and registry server for managing protobuf schemas and generating client code. It provides a simple workflow to push/pull protobuf packages to/from a central registry, validate schemas, and generate code in multiple languages using custom plugins.
You can view the documentation at docs.protodex.dev.
Features
- Full-Featured CLI - Familiar push/pull workflow for schema management
- Built-in validation - Protobuf syntax validation using protoc
- Code generation - Generate Go, Python, TypeScript, Java etc. clients
- Custom plugins - Support for any protoc plugin (GRPC, Twirp, gRPC-Gateway, Validate, etc.)
Quick Start
Installation
Download pre-built binaries:
Visit the releases page for your OS.
Build from source:
git clone https://github.com/sirrobot01/protodex
cd protodex
go build -o bin/protodex ./cmd/protodex
Install via Go:
go install github.com/sirrobot01/protodex/cmd/protodex@latest
Registry Setup
The registry server is where you push and pull your protobuf packages. It's optional if you only need local code generation.
Start a local registry server (default port 8080):
protodex serve --port 8080 --data-dir ./data # data-dir defaults to ~/.protodex/data
The server provides:
- Web interface at
http://localhost:8080
- REST API at
http://localhost:8080/api
It currently uses a local SQLite database for now. I plan to add support for external databases in the future.
Configuration
Create a protodex.yaml
in your project root:
protodex init my-service
Project Configuration (protodex.yaml)
package:
name: user-service
description: User management service schemas
files:
exclude: []
base_dir: .
gen:
languages:
- name: go
output_dir: ./gen/go
module_path: github.com/myuser/user-service
deps:
- name: google/protobuf
type: google-well-known
source: ""
Custom Plugin Configuration
Protodex supports any protoc plugin through project configuration:
# protodex.yaml
# Global plugins (applied to all languages)
plugins:
- name: validate
command: protoc-gen-validate
required: false
options:
lang: go
gen:
languages:
- name: go
output_dir: ./gen/go
module_path: github.com/myuser/client
# Language-specific plugins
plugins:
- name: twirp
command: protoc-gen-twirp
required: false
options:
package_prefix: github.com/myuser/client
- name: python
output_dir: ./gen/python
- name: java
output_dir: ./gen/java
plugins:
- name: grpc-gateway
command: protoc-gen-grpc-gateway
required: false
Plugin Configuration Fields:
name
: Plugin identifier
command
: Plugin executable name (e.g., protoc-gen-twirp
)
output_dir
: Optional output directory for plugin-generated files
required
: Whether plugin must be installed (validates before generation)
options
: Plugin-specific options
Contributing
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests for new functionality
- Run the test suite
- Submit a pull request
TODO
- Support external databases (PostgreSQL, MySQL)
- Support for a better file storage backend (S3, GCS)
- Add a more robust authentication system
- Improve web interface with package browsing and search
- A more advanced plugin management system
- Support for custom generators
License
MIT License - see LICENCE file for details.