0
# Command Line Tools
1

2
Jsonnet provides two command-line tools: `jsonnet` for evaluating Jsonnet code and generating JSON output, and `jsonnetfmt` for formatting and linting Jsonnet source code. Both tools offer extensive configuration options and support various output modes.
3

4
## Capabilities
5

6
### jsonnet Command
7

8
Primary command-line tool for evaluating Jsonnet files and generating JSON output with support for multiple output modes, external variables, and import path configuration.
9

10
```bash { .api }
11
jsonnet [options] <filename>
12

13
# Core Options:
14
-o, --output-file <file>     Write output to file instead of stdout
15
-m, --multi <dir>           Write multiple files to directory
16
-S, --stream                Write JSON stream output
17
-e, --exec                  Evaluate argument as Jsonnet code instead of filename
18

19
# Variable Options:
20
-V, --ext-str <var>=<val>   External string variable
21
-C, --ext-code <var>=<val>  External code variable
22
-A, --tla-str <var>=<val>   Top-level string argument
23
--tla-code <var>=<val>      Top-level code argument
24

25
# Import Options:
26
-J, --jpath <dir>           Add library search directory
27

28
# VM Options:
29
--max-stack <n>             Maximum stack depth (default: 500)
30
--gc-min-objects <n>        GC minimum objects (default: 1000)
31
--gc-growth-trigger <x>     GC growth trigger (default: 2.0)
32
--max-trace <n>             Maximum stack trace lines (default: 20)
33
--string-output             Output raw string instead of JSON
34

35
# Format Options:
36
--yaml-stream               Output YAML stream format
37
--yaml-out                  Output YAML format instead of JSON
38
```
39

40
### jsonnetfmt Command
41

42
Code formatter for Jsonnet source code with extensive style configuration options and support for in-place editing.
43

44
```bash { .api }
45
jsonnetfmt [options] [filename...]
46

47
# Core Options:
48
-i, --in-place              Modify files in place
49
-o, --output-file <file>    Write output to file
50
--test                      Test if input is correctly formatted (exit status only)
51

52
# Style Options:
53
--indent <n>                Indentation level (default: 2 spaces)
54
--max-blank-lines <n>       Maximum consecutive blank lines (default: 2)
55
--string-style <style>      String literal style: d(ouble), s(ingle), l(eave)
56
--comment-style <style>     Comment style: h(ash), s(lash), l(eave)
57

58
# Formatting Options:
59
--pad-arrays                Add extra space inside arrays
60
--pad-objects               Add extra space inside objects
61
--pretty-field-names        Use syntax sugar for field names when possible
62
--sort-imports              Sort top-level imports alphabetically
63
--debug-desugaring          Show desugared output for debugging
64
```
65

66
## Usage Examples
67

68
### Basic jsonnet Usage
69

70
**Evaluate file to stdout:**
71
```bash
72
jsonnet config.jsonnet
73
```
74

75
**Save output to file:**
76
```bash
77
jsonnet -o output.json config.jsonnet
78
```
79

80
**Evaluate code directly:**
81
```bash
82
jsonnet -e '{ greeting: "Hello World!" }'
83
```
84

85
### External Variables
86

87
**String variables:**
88
```bash
89
jsonnet -V environment=production -V region=us-west-1 config.jsonnet
90
```
91

92
**Code variables:**
93
```bash
94
jsonnet -C database_config='{ host: "db.prod.com", port: 5432 }' config.jsonnet
95
```
96

97
**Mixed variables:**
98
```bash
99
jsonnet \
100
  -V env=production \
101
  -V debug=false \
102
  -C features='["auth", "logging"]' \
103
  -A service_name=api-server \
104
  config.jsonnet
105
```
106

107
### Top-Level Arguments
108

109
For Jsonnet files that are functions:
110
```bash
111
# deployment.jsonnet is a function: function(cluster, replicas=3) { ... }
112
jsonnet -A cluster=production --tla-code replicas=5 deployment.jsonnet
113
```
114

115
### Import Paths
116

117
```bash
118
jsonnet -J /usr/local/lib/jsonnet -J ./lib config.jsonnet
119
```
120

121
### Multi-File Output
122

123
```bash
124
# For Jsonnet that outputs an object with filenames as keys
125
jsonnet -m ./output-dir multi-file-config.jsonnet
126

127
# Creates multiple files in output-dir/
128
# Each key becomes a filename, each value becomes file content
129
```
130

131
### JSON Stream Output
132

133
```bash
134
# For Jsonnet that outputs an array of objects
135
jsonnet -S stream-config.jsonnet
136

137
# Outputs each array element as a separate JSON object
138
```
139

140
### YAML Output
141

142
```bash
143
jsonnet --yaml-out config.jsonnet > config.yaml
144
jsonnet --yaml-stream stream-config.jsonnet > stream.yaml
145
```
146

147
### VM Configuration
148

149
```bash
150
jsonnet \
151
  --max-stack 1000 \
152
  --gc-min-objects 5000 \
153
  --gc-growth-trigger 3.0 \
154
  --max-trace 50 \
155
  large-config.jsonnet
156
```
157

158
### String Output Mode
159

160
```bash
161
# Output raw strings without JSON encoding
162
jsonnet --string-output -e '"Hello World!"'
163
# Output: Hello World! (not "Hello World!")
164
```
165

166
## jsonnetfmt Usage
167

168
### Basic Formatting
169

170
**Format to stdout:**
171
```bash
172
jsonnetfmt config.jsonnet
173
```
174

175
**Format in place:**
176
```bash
177
jsonnetfmt -i config.jsonnet
178
```
179

180
**Format multiple files:**
181
```bash
182
jsonnetfmt -i *.jsonnet lib/*.jsonnet
183
```
184

185
**Test formatting (exit code only):**
186
```bash
187
jsonnetfmt --test config.jsonnet
188
echo $?  # 0 if correctly formatted, 1 if needs formatting
189
```
190

191
### Style Configuration
192

193
**Custom indentation:**
194
```bash
195
jsonnetfmt --indent 4 config.jsonnet
196
```
197

198
**String and comment style:**
199
```bash
200
jsonnetfmt --string-style s --comment-style h config.jsonnet
201
```
202

203
**Padding and spacing:**
204
```bash
205
jsonnetfmt --pad-arrays --pad-objects config.jsonnet
206
```
207

208
**Import sorting:**
209
```bash
210
jsonnetfmt --sort-imports --pretty-field-names config.jsonnet
211
```
212

213
**Complete style configuration:**
214
```bash
215
jsonnetfmt \
216
  --indent 4 \
217
  --max-blank-lines 1 \
218
  --string-style d \
219
  --comment-style s \
220
  --pad-arrays \
221
  --pad-objects \
222
  --pretty-field-names \
223
  --sort-imports \
224
  -i *.jsonnet
225
```
226

227
## Integration Examples
228

229
### Build System Integration
230

231
**Makefile:**
232
```makefile
233
%.json: %.jsonnet
234
	jsonnet -o $@ $<
235

236
config-prod.json: config.jsonnet
237
	jsonnet -V environment=production -o $@ $<
238

239
format:
240
	jsonnetfmt -i *.jsonnet
241

242
.PHONY: format
243
```
244

245
**Shell script for deployment:**
246
```bash
247
#!/bin/bash
248
set -e
249

250
ENVIRONMENT=${1:-development}
251
OUTPUT_DIR="./generated"
252

253
echo "Generating configuration for environment: $ENVIRONMENT"
254

255
mkdir -p "$OUTPUT_DIR"
256

257
jsonnet \
258
  -V environment="$ENVIRONMENT" \
259
  -V timestamp="$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
260
  -C build_info="$(git rev-parse HEAD)" \
261
  -m "$OUTPUT_DIR" \
262
  deployment.jsonnet
263

264
echo "Configuration generated in $OUTPUT_DIR"
265
```
266

267
### CI/CD Pipeline
268

269
**GitHub Actions:**
270
```yaml
271
name: Validate Jsonnet
272
on: [push, pull_request]
273

274
jobs:
275
  validate:
276
    runs-on: ubuntu-latest
277
    steps:
278
      - uses: actions/checkout@v2
279
      - name: Install Jsonnet
280
        run: |
281
          wget https://github.com/google/jsonnet/releases/download/v0.21.0/jsonnet-bin-v0.21.0-linux.tar.gz
282
          tar -xzf jsonnet-bin-v0.21.0-linux.tar.gz
283
          sudo mv jsonnet jsonnetfmt /usr/local/bin/
284
      
285
      - name: Check formatting
286
        run: |
287
          find . -name "*.jsonnet" -exec jsonnetfmt --test {} \;
288
      
289
      - name: Validate syntax
290
        run: |
291
          find . -name "*.jsonnet" -exec jsonnet {} \; > /dev/null
292
```
293

294
### Docker Integration
295

296
**Dockerfile:**
297
```dockerfile
298
FROM alpine:latest
299

300
RUN apk add --no-cache jsonnet
301

302
COPY configs/ /configs/
303
WORKDIR /configs
304

305
ENTRYPOINT ["jsonnet"]
306
CMD ["--help"]
307
```
308

309
**Usage:**
310
```bash
311
docker build -t my-jsonnet .
312
docker run --rm -v $(pwd)/output:/output my-jsonnet -m /output config.jsonnet
313
```
314

315
### Advanced Usage
316

317
**Configuration management:**
318
```bash
319
#!/bin/bash
320
# generate-configs.sh
321

322
environments=("development" "staging" "production")
323
services=("api" "worker" "scheduler")
324

325
for env in "${environments[@]}"; do
326
  for service in "${services[@]}"; do
327
    output_file="${service}-${env}.json"
328
    echo "Generating $output_file..."
329
    
330
    jsonnet \
331
      -V environment="$env" \
332
      -V service="$service" \
333
      -A replicas="$(if [ "$env" = "production" ]; then echo 3; else echo 1; fi)" \
334
      -o "configs/$output_file" \
335
      templates/service.jsonnet
336
  done
337
done
338
```
339

340
**With templating and includes:**
341
```bash
342
# Create library of reusable components
343
mkdir -p lib/
344

345
# Generate configurations with common libraries
346
jsonnet \
347
  -J lib/ \
348
  -J /usr/local/share/jsonnet-libs/ \
349
  -V cluster="$(kubectl config current-context)" \
350
  -C secrets="$(kubectl get secret app-secrets -o json)" \
351
  -m ./k8s-manifests/ \
352
  kubernetes.jsonnet
353
```
354

355
**Validation and testing:**
356
```bash
357
#!/bin/bash
358
# validate-configs.sh
359

360
echo "Validating Jsonnet syntax..."
361
find . -name "*.jsonnet" | while read -r file; do
362
  if ! jsonnet "$file" > /dev/null 2>&1; then
363
    echo "Syntax error in $file"
364
    exit 1
365
  fi
366
done
367

368
echo "Checking formatting..."
369
if ! find . -name "*.jsonnet" -exec jsonnetfmt --test {} \;; then
370
  echo "Formatting issues found. Run: find . -name '*.jsonnet' -exec jsonnetfmt -i {} \;"
371
  exit 1
372
fi
373

374
echo "All validations passed!"
375
```