Proto

Proto codegen, registry management, and validation commands.

riven proto generate

Run proto codegen with automatic dependency resolution. Fetches any registry dependencies referenced in your package.json before generating TypeScript or Python stubs.

bash

# Default directories
riven proto generate
 
# Custom directories
riven proto generate --proto-dir ./api --output-dir ./src/generated
 
# Skip fetching registry deps (offline mode)
riven proto generate --no-fetch

Option	Default	Description
`--proto-dir`	`./proto`	Proto source directory
`--output-dir`	`./src/__generated__`	Generated code output directory
`--no-fetch`	—	Skip auto-fetching registry dependencies

riven proto lint

Lint proto files against organization rules using buf lint under the hood.

bash

riven proto lint
riven proto lint --proto-dir ./api

riven proto breaking

Detect breaking changes in your proto files by comparing against a published version in the registry. Defaults to comparing against the latest published version.

bash

# Compare against latest
riven proto breaking
 
# Compare against a specific version
riven proto breaking --against v1.2.0
 
# Specify module explicitly
riven proto breaking --module my-service --against v1.0.0

riven proto publish

Publish proto modules to the registry. Module name and version are auto-detected from buf.yaml and git tags, but can be overridden.

bash

# Auto-detect everything
riven proto publish
 
# Explicit version
riven proto publish --version 2.0.0
 
# Dry run
riven proto publish --dry-run

Option	Description
`--proto-dir`	Proto source directory (default: `./proto`)
`--module`	Module name (auto-detected from buf.yaml)
`--version`	Module version (auto-detected from git tags)
`--description`	Module description
`--owner`	Module owner (auto-detected from git)
`--dry-run`	Show what would be published without uploading

riven proto pull

Fetch proto module dependencies from the registry. Uses a lockfile by default for reproducible builds.

bash

# Fetch using lockfile
riven proto pull
 
# Ignore lockfile and resolve fresh versions
riven proto pull --update

riven proto search

Search or list proto modules in the registry. Supports substring matching on module names and filtering by owner.

bash

# List all modules
riven proto search
 
# Search by name
riven proto search user-service
 
# Filter by owner, JSON output
riven proto search --owner platform-team --format json

riven proto cache

Manage the global proto cache at ~/.riven/protos/.

bash

# Show cache size and contents
riven proto cache list
 
# Clear all cached protos
riven proto cache clean

protoDeps Configuration

Declare registry-based proto dependencies in your package.json:

json

{
  "riven": {
    "protoDeps": {
      "riven.billing.v1": "*",
      "riven.tasks.v1": "0.1.0"
    }
  }
}

Dependencies are resolved from the registry and cached globally at ~/.riven/protos/. Packages with protoDeps but no proto/ directory automatically create a temp proto directory for codegen.

rpcClients Configuration

Declare remote service RPC clients your service depends on:

json

{
  "riven": {
    "rpcClients": ["com.riven.search.v1.SearchService"]
  }
}

Services listed under rpcClients only get *Client.ts generation (no ServiceBase, Prisma, Meta, or HttpRoutes). This lets a service declare which remote services' typed RPC clients it needs without generating server-side artifacts.

Typical Workflow

A standard proto development workflow with the registry:

bash

# 1. Pull latest dependencies
riven proto pull
 
# 2. Edit your .proto files
#    ...
 
# 3. Lint to catch style issues
riven proto lint
 
# 4. Check for breaking changes
riven proto breaking
 
# 5. Generate code
riven proto generate
 
# 6. Publish to registry
riven proto publish

PreviousAuth NextService Scaffolding