0
# CLI Tools
1

2
Command-line utilities for static code generation, TypeScript definition generation, and protobuf schema compilation with multiple output formats and optimization options.
3

4
## Capabilities
5

6
### pbjs Command
7

8
Main command-line tool for converting .proto files to JavaScript code with various output formats and optimization options.
9

10
```bash { .api }
11
# Basic usage
12
pbjs [options] file1.proto file2.proto ...
13

14
# Common options
15
pbjs -t static-module -w commonjs -o output.js input.proto
16
pbjs -t json -o schema.json input.proto  
17
pbjs -t static -w es6 -o output.mjs input.proto
18
```
19

20
**Core Options:**
21

22
```bash { .api }
23
# Target formats (-t, --target)
24
-t static-module    # Static module with embedded types
25
-t static          # Static code generation  
26
-t json            # JSON descriptor
27
-t json-module     # JSON descriptor as module
28

29
# Wrapper formats (-w, --wrap)  
30
-w commonjs        # CommonJS module.exports
31
-w amd             # AMD define()
32
-w es6             # ES6 export
33
-w closure         # Google Closure
34
-w default         # Default wrapper
35

36
# Output options
37
-o, --out          # Output file path
38
-r, --root         # Root directory for imports
39
-p, --path         # Additional include paths
40
```
41

42
**Usage Examples:**
43

44
```bash
45
# Generate CommonJS static module
46
pbjs -t static-module -w commonjs -o messages.js messages.proto
47

48
# Generate ES6 module
49
pbjs -t static-module -w es6 -o messages.mjs messages.proto
50

51
# Generate JSON schema
52
pbjs -t json -o schema.json messages.proto
53

54
# Multiple input files
55
pbjs -t static-module -w commonjs -o bundle.js user.proto order.proto
56

57
# With include paths
58
pbjs -t static-module -w commonjs -p ./protos -p ./common -o output.js main.proto
59

60
# Minified output
61
pbjs -t static-module -w commonjs --no-comments --no-delimited -o min.js input.proto
62
```
63

64
### pbts Command
65

66
TypeScript definition generator that creates .d.ts files from JavaScript protobuf modules.
67

68
```bash { .api }  
69
# Basic usage
70
pbts [options] input.js
71

72
# Common usage
73
pbts -o definitions.d.ts generated.js
74
pbts --main -o index.d.ts generated.js
75
```
76

77
**Core Options:**
78

79
```bash { .api }
80
# Output options
81
-o, --out          # Output .d.ts file path
82
-n, --name         # Global type name for definitions
83
-m, --main         # Generate main entry point definitions
84

85
# Generation options  
86
--no-comments      # Omit comments in output
87
--global           # Generate global definitions
88
```
89

90
**Usage Examples:**
91

92
```bash
93
# Generate TypeScript definitions
94
pbts -o messages.d.ts messages.js
95

96
# Generate main entry point definitions
97
pbts --main -o index.d.ts generated.js
98

99
# Global type definitions
100
pbts --global -n MyProtobuf -o global.d.ts messages.js
101

102
# Multiple source files
103
pbts -o combined.d.ts file1.js file2.js
104
```
105

106
### Advanced Generation Options
107

108
Advanced options for customizing code generation behavior and output format.
109

110
```bash { .api }
111
# pbjs advanced options
112
--keep-case        # Keep original field case instead of camelCase  
113
--alt-comment      # Use alternate comment parsing
114
--no-create        # Don't generate create() methods
115
--no-encode        # Don't generate encode() methods  
116
--no-decode        # Don't generate decode() methods
117
--no-verify        # Don't generate verify() methods
118
--no-convert       # Don't generate convert methods
119
--no-delimited     # Don't generate delimited methods
120
--no-beautify      # Don't beautify generated code
121
--no-comments      # Omit comments from output
122
--force-long       # Force using Long for int64 fields
123
--force-number     # Force using number for int64 fields
124
--force-message    # Force message constructor style
125
```
126

127
**Usage Examples:**
128

129
```bash
130
# Minimal generation (smallest output)
131
pbjs -t static-module -w commonjs --no-comments --no-beautify \
132
     --no-delimited --no-verify -o minimal.js input.proto
133

134
# Performance optimized  
135
pbjs -t static-module -w commonjs --force-number \
136
     --no-create --no-convert -o fast.js input.proto
137

138
# Keep original proto field names
139
pbjs -t static-module -w commonjs --keep-case -o original.js input.proto
140

141
# Alternative comment parsing for complex protos
142
pbjs -t static-module -w commonjs --alt-comment -o parsed.js input.proto
143
```
144

145
### Multiple Target Formats
146

147
Different output formats for various use cases and environments.
148

149
```bash { .api }
150
# Static module generation
151
pbjs -t static-module -w commonjs -o static.js input.proto
152

153
# JSON descriptor export
154
pbjs -t json -o descriptor.json input.proto
155

156
# JSON module export  
157
pbjs -t json-module -w commonjs -o descriptor.js input.proto
158

159
# Static code generation (separate files)
160
pbjs -t static -w commonjs -o output/ input.proto
161
```
162

163
**Target Format Examples:**
164

165
```bash
166
# Static module (recommended for most use cases)
167
pbjs -t static-module -w commonjs messages.proto
168
# Output: Single file with embedded message constructors
169

170
# JSON descriptor (for dynamic loading)
171
pbjs -t json messages.proto  
172
# Output: JSON representation of proto schema
173

174
# Static generation (separate files)
175
pbjs -t static messages.proto
176
# Output: Multiple files, one per message type
177
```
178

179
### Integration with Build Systems
180

181
Examples of integrating protobuf compilation into various build systems.
182

183
```bash { .api }
184
# npm scripts in package.json
185
{
186
  "scripts": {
187
    "build:proto": "pbjs -t static-module -w commonjs -o src/proto.js proto/*.proto",
188
    "build:types": "pbts -o src/proto.d.ts src/proto.js",
189
    "build": "npm run build:proto && npm run build:types"
190
  }
191
}
192

193
# Makefile integration
194
proto:
195
	pbjs -t static-module -w commonjs -o src/messages.js proto/*.proto
196
	pbts -o src/messages.d.ts src/messages.js
197

198
# Webpack integration (webpack.config.js)
199
module.exports = {
200
  module: {
201
    rules: [
202
      {
203
        test: /\.proto$/,
204
        use: [
205
          {
206
            loader: 'protobuf-loader',
207
            options: {
208
              target: 'static-module',
209
              wrap: 'commonjs'
210
            }
211
          }
212
        ]
213
      }
214
    ]
215
  }
216
};
217
```
218

219
### Output Format Examples
220

221
Examples of generated code for different target formats.
222

223
**Static Module Output:**
224

225
```javascript
226
// Generated by pbjs -t static-module -w commonjs
227
"use strict";
228

229
var $protobuf = require("protobufjs/minimal");
230
var $root = ($protobuf.roots.default || ($protobuf.roots.default = new $protobuf.Root()));
231

232
$root.User = (function() {
233
    function User(properties) {
234
        if (properties)
235
            for (var keys = Object.keys(properties), i = 0; i < keys.length; ++i)
236
                if (properties[keys[i]] != null)
237
                    this[keys[i]] = properties[keys[i]];
238
    }
239
    
240
    User.prototype.id = 0;
241
    User.prototype.name = "";
242
    
243
    User.create = function create(properties) {
244
        return new User(properties);
245
    };
246
    
247
    User.encode = function encode(message, writer) {
248
        if (!writer) writer = $Writer.create();
249
        if (message.id != null && message.hasOwnProperty("id"))
250
            writer.uint32(8).uint32(message.id);
251
        if (message.name != null && message.hasOwnProperty("name"))
252
            writer.uint32(18).string(message.name);
253
        return writer;
254
    };
255
    
256
    // ... decode, verify, etc.
257
    
258
    return User;
259
})();
260

261
module.exports = $root;
262
```
263

264
**JSON Descriptor Output:**
265

266
```json
267
{
268
  "nested": {
269
    "User": {
270
      "fields": {
271
        "id": {
272
          "type": "uint32",
273
          "id": 1
274
        },
275
        "name": {
276
          "type": "string", 
277
          "id": 2
278
        }
279
      }
280
    }
281
  }
282
}
283
```
284

285
**TypeScript Definitions Output:**
286

287
```typescript
288
// Generated by pbts
289
import * as $protobuf from "protobufjs";
290

291
export interface IUser {
292
    id?: (number|null);
293
    name?: (string|null);
294
}
295

296
export class User implements IUser {
297
    constructor(properties?: IUser);
298
    public id: number;
299
    public name: string;
300
    public static create(properties?: IUser): User;
301
    public static encode(message: IUser, writer?: $protobuf.Writer): $protobuf.Writer;
302
    public static encodeDelimited(message: IUser, writer?: $protobuf.Writer): $protobuf.Writer;
303
    public static decode(reader: ($protobuf.Reader|Uint8Array), length?: number): User;
304
    public static decodeDelimited(reader: ($protobuf.Reader|Uint8Array)): User;
305
    public static verify(message: { [k: string]: any }): (string|null);
306
    public static fromObject(object: { [k: string]: any }): User;
307
    public static toObject(message: User, options?: $protobuf.IConversionOptions): { [k: string]: any };
308
    public toJSON(): { [k: string]: any };
309
    public static getTypeUrl(typeUrlPrefix?: string): string;
310
}
311
```
312

313
### Performance Optimization
314

315
Optimization strategies and options for generated code performance.
316

317
```bash { .api }
318
# Size optimization
319
pbjs -t static-module -w commonjs --no-comments --no-beautify \
320
     --no-delimited --no-convert -o optimized.js input.proto
321

322
# Speed optimization  
323
pbjs -t static-module -w commonjs --force-number \
324
     --no-verify --no-create -o fast.js input.proto
325

326
# Memory optimization
327
pbjs -t static-module -w commonjs --force-message \
328
     --no-convert -o memory.js input.proto
329
```
330

331
**Optimization Trade-offs:**
332

333
```bash
334
# Smaller bundle size (removes optional methods)
335
--no-create        # -15% size, lose convenience methods
336
--no-verify        # -20% size, lose validation
337
--no-convert       # -25% size, lose object conversion
338
--no-delimited     # -5% size, lose delimited encoding
339

340
# Faster execution (use primitives over objects)
341
--force-number     # +30% speed for int64, lose precision safety
342
--force-message    # +15% speed, consistent object usage
343

344
# Better compatibility
345
--keep-case        # Preserve proto field names
346
--force-long       # Ensure int64 precision
347
```
348

349
### Error Handling and Debugging
350

351
Common issues and debugging techniques for CLI tools.
352

353
```bash { .api }
354
# Verbose output for debugging
355
pbjs -t static-module -w commonjs --verbose -o debug.js input.proto
356

357
# Dependency resolution issues
358
pbjs -t static-module -w commonjs -p ./protos -p ../common \
359
     --verbose -o output.js main.proto
360

361
# Import path debugging
362
pbjs -t static-module -w commonjs -r ./src/protos \
363
     --verbose -o generated.js **/*.proto
364
```
365

366
**Common Error Solutions:**
367

368
```bash
369
# "Cannot resolve import" error
370
pbjs -p ./additional-path -p ./another-path input.proto
371

372
# "Duplicate definition" error  
373
pbjs --alt-comment input.proto  # Try alternate parsing
374

375
# "Invalid syntax" error
376
# Check proto file syntax with protoc first:
377
protoc --syntax_out=/dev/null input.proto
378

379
# TypeScript generation errors
380
pbts --verbose -o types.d.ts generated.js
381
```
382

383
### Automation and Workflows
384

385
Automated workflows for protobuf compilation in CI/CD pipelines.
386

387
```bash { .api }
388
# GitHub Actions workflow
389
name: Build Protobuf
390
on: [push, pull_request]
391
jobs:
392
  build:
393
    runs-on: ubuntu-latest
394
    steps:
395
      - uses: actions/checkout@v2
396
      - uses: actions/setup-node@v2
397
        with:
398
          node-version: '16'
399
      - run: npm install -g protobufjs-cli
400
      - run: pbjs -t static-module -w commonjs -o src/proto.js proto/*.proto
401
      - run: pbts -o src/proto.d.ts src/proto.js
402

403
# Docker build integration
404
FROM node:16-alpine
405
RUN npm install -g protobufjs-cli
406
COPY proto/ /app/proto/
407
WORKDIR /app
408
RUN pbjs -t static-module -w commonjs -o generated.js proto/*.proto
409
RUN pbts -o generated.d.ts generated.js
410
```
411

412
**Automated Build Scripts:**
413

414
```bash
415
#!/bin/bash
416
# build-proto.sh
417

418
set -e
419

420
PROTO_DIR="./proto"
421
OUTPUT_DIR="./src/generated"
422
TEMP_JS="$OUTPUT_DIR/temp.js"
423
FINAL_JS="$OUTPUT_DIR/proto.js"
424
FINAL_TS="$OUTPUT_DIR/proto.d.ts"
425

426
mkdir -p "$OUTPUT_DIR"
427

428
echo "Generating JavaScript..."
429
pbjs -t static-module -w commonjs \
430
     -o "$TEMP_JS" \
431
     "$PROTO_DIR"/*.proto
432

433
echo "Generating TypeScript definitions..."
434
pbts -o "$FINAL_TS" "$TEMP_JS"
435

436
mv "$TEMP_JS" "$FINAL_JS"
437

438
echo "Generated:"
439
echo "  $FINAL_JS"
440
echo "  $FINAL_TS"
441

442
# Validate generated files
443
node -e "require('$FINAL_JS')" && echo "✓ JavaScript module loads correctly"
444
```
445

446
## Types
447

448
```bash { .api }
449
# CLI exit codes
450
0  # Success
451
1  # General error
452
2  # Invalid arguments  
453
3  # File not found
454
4  # Syntax error in proto
455
5  # Generation error
456

457
# File extensions
458
.proto    # Protocol buffer definition files
459
.js       # Generated JavaScript modules
460
.d.ts     # Generated TypeScript definitions  
461
.json     # JSON descriptor files
462
.mjs      # ES6 module files
463
```