PulseRPC CLI Reference

The pulserpc command-line interface supports multiple modes of operation for parsing IDL files, generating code, and running the web UI.

Usage

pulserpc [flags] <idl-file>

Global Flags

Core Flags

Flag Type Description
-validate bool Validate the IDL after parsing. Checks for semantic errors like undefined types, missing namespaces, etc.
-to-json string Write parsed IDL as JSON to the specified file. Useful for debugging or inspecting the parsed AST.
-from-json string Read a JSON file and generate IDL text on STDOUT. The reverse of -to-json.
-plugin string Code generation plugin to use (e.g., python-client-server, go-client-server).
-ui bool Start the embedded web UI server for interactive testing and code generation.
-ui-port int Port for the web UI server (default: 8080).
-openapi-to-pulse string Convert OpenAPI spec (YAML/JSON) to Pulse IDL. Specify path to OpenAPI file.
-pulse-to-openapi string Convert Pulse IDL to OpenAPI spec. Specify path to Pulse IDL file.

Output Directory Flags

Flag Type Description
-dir string Output directory for generated code and runtime files. Required when using -plugin.
-silent bool Suppress file generation output. Useful for scripting or when output is too verbose.
-generate-test-files bool Generate test files (test_server.*, test_client.*) along with regular output.
-output-dir string Output directory for OpenAPI translation. Default: ./generated. Used with -openapi-to-pulse or -pulse-to-openapi.
-openapi-version string Target OpenAPI version for Pulse → OpenAPI conversion: 3.0 or 3.1 (default). Used with -pulse-to-openapi.
-strict bool Treat warnings as errors during OpenAPI translation. Exit with non-zero code if any warnings are issued.

Code Generation Plugins

Available Plugins

Plugin Description
python-client-server Generate Python client and server code
go-client-server Generate Go client and server code
java-client-server Generate Java client and server code
ts-client-server Generate TypeScript client and server code
csharp-client-server Generate C# client and server code

Plugin-Specific Flags

Go Plugin (go-client-server)

Flag Type Description
-go-module string Override Go module path for pulserpc imports. Auto-detected from go.mod if not specified.
-inline-runtime bool Place runtime files inline with generated code. Useful for playground/testing environments.

Java Plugin (java-client-server)

Flag Type Description
-package string Base package name for generated Java classes. Required (e.g., com.example.server).
-json-lib string JSON library to use: jackson (default) or gson.

TypeScript Plugin (ts-client-server)

Flag Type Description
-package string Package prefix for generated types and classes. Used for namespace isolation.

Python Plugin (python-client-server)

Flag Type Description
-package string Base import path for namespace packages and runtime imports. Use this when generating multi-namespace Python output.

C# Plugin (csharp-client-server)

Flag Type Description
-package string Base namespace for generated C# code (e.g., MyApp.Lib.Rpc). When set, generated code uses this as a prefix for cross-namespace imports and runtime references. If not set, uses PulseRPC namespace directly (backwards compatible).

Migration and Compatibility Notes

When using the -package flag with C# code generation:

Troubleshooting

Common issues when using -package:

  1. Missing namespace directories: Ensure the output directory exists and is writable.
  2. Using statement errors: Verify the base namespace matches the generated directory structure. For example, -package MyApp.Lib.Rpc expects MyApp/Lib/Rpc/ directories.
  3. Cross-namespace type resolution: When referencing types from other namespaces, ensure the namespace is correctly set in your IDL files.

Common Usage Examples

Validate an IDL File

Check your IDL file for syntax and semantic errors:

pulserpc -validate api/service.pulse

Pretty-Print an IDL File

Display a human-readable summary of interfaces, structs, and enums:

pulserpc api/service.pulse

Convert IDL to JSON

Export the parsed AST as JSON for inspection or debugging:

pulserpc -to-json service.json api/service.pulse

Generate Python Code

Generate Python client and server code:

pulserpc -plugin python-client-server -dir ./output api/service.pulse

Generate Java Code with Custom Package

Generate Java code with a specific base package:

pulserpc -plugin java-client-server -dir ./src/main/java \
  -package com.example.api api/service.pulse

Generate Go Code with Inline Runtime

Generate Go code with runtime files embedded (useful for testing):

pulserpc -plugin go-client-server -dir ./output -inline-runtime api/service.pulse

Generate TypeScript Code with Package Prefix

Generate TypeScript with a namespace prefix:

pulserpc -plugin ts-client-server -dir ./src -package '@mycompany/api' api/service.pulse

Generate Test Files

Generate additional test files for integration testing:

pulserpc -plugin python-client-server -dir ./output -generate-test-files api/service.pulse

This creates test_server.py and test_client.py in addition to the normal output files.

Silent Mode

Suppress file generation output:

pulserpc -plugin go-client-server -dir ./output -silent api/service.pulse

Start the Web UI

Launch the interactive web UI on a custom port:

pulserpc -ui -ui-port 9090

Then open http://localhost:9090 in your browser.

OpenAPI Translation

Convert OpenAPI to Pulse IDL

Import an existing OpenAPI specification and generate Pulse IDL:

pulserpc -openapi-to-pulse api-spec.yaml -output-dir ./idl

This creates api-spec.yaml.pulse in the output directory.

Convert Pulse IDL to OpenAPI

Export a Pulse IDL file as an OpenAPI specification:

pulserpc -pulse-to-openapi service.pulse -output-dir ./specs

This creates service.openapi.yaml in the output directory.

Specify OpenAPI Version

Generate OpenAPI 3.0 instead of the default 3.1:

pulserpc -pulse-to-openapi service.pulse -output-dir ./specs -openapi-version 3.0

Strict Mode

Treat warnings as errors during conversion:

pulserpc -openapi-to-pulse api-spec.yaml -output-dir ./idl -strict

The command will exit with a non-zero code if any warnings are issued (e.g., unsupported features like oneOf or security schemes).

Combined Conversion and Code Generation

Convert an OpenAPI spec and immediately generate code:

# Step 1: Convert to Pulse
pulserpc -openapi-to-pulse petstore.yaml -output-dir ./generated

# Step 2: Generate Python code
pulserpc -plugin python-client-server -dir ./client ./generated/petstore.yaml.pulse

Using with Docker

When running PulseRPC via Docker, mount your working directory and pass flags as usual:

docker run --rm -v $(pwd):/work ghcr.io/coopernurse/pulserpc:latest \
  -plugin python-client-server -dir ./output api/service.pulse

Start the web UI with Docker:

docker run --rm -p 8080:8080 -v $(pwd):/work ghcr.io/coopernurse/pulserpc:latest -ui

Flag Mutually Exclusivity

Some flag combinations are not allowed:

Getting Help

Display all available flags and their descriptions:

pulserpc -h

For plugin-specific flags, use the -h flag with a plugin:

pulserpc -plugin java-client-server -h

Next Steps