postman-cli 1.58.0 → 1.60.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/man/postman.1 +693 -48
  2. package/package.json +6 -6
package/man/postman.1 CHANGED
@@ -1,4 +1,4 @@
1
- .TH POSTMAN 1 "2026-09-17" "v1.58.0" "Postman CLI Manual"
1
+ .TH POSTMAN 1 "2026-09-21" "v1.60.0" "Postman CLI Manual"
2
2
  .SH NAME
3
3
  postman \- Command\-line companion utility for Postman
4
4
  .SH SYNOPSIS
@@ -8,6 +8,13 @@ postman \- Command\-line companion utility for Postman
8
8
  The Postman CLI is a command\-line companion utility that brings the power of Postman platform directly to your terminal. It enables you to run collections, lint APIs, manage monitors, and integrate API testing into CI/CD pipelines.
9
9
  .br
10
10
  Note: All commands support the --help option for more information..
11
+ .SH CLAUDE CODE PLUGIN
12
+ Claude Code users and agents can use the Postman Plugin for Claude Code for full API lifecycle management including documentation, collections, workspaces, environments, mocks, monitors right from your repository.
13
+ .br
14
+ Install it with: claude plugin install postman@claude\-plugins\-official
15
+ .br
16
+ Then start Claude Code and run: /postman:setup
17
+ .br
11
18
  .SH OPTIONS
12
19
  .TP
13
20
  .B \-v, \-\-version
@@ -41,15 +48,15 @@ Specify the region for authentication. Use "eu" for EU region.
41
48
  Show detailed error information
42
49
 
43
50
  .SS "signup"
44
- Sign up to keep the work you created as a guest (claims your guest workspace). By default prints a single\-use sign\-up URL to open in a browser; \-\-browser signs up in a browser and signs this CLI in.
51
+ Sign up to keep the work you created as a guest (claims your guest workspace). Waits and signs this CLI in once the sign\-up is completed in a browser — opening that browser here on a terminal, or printing the URL to hand over when output is piped.
45
52
 
46
53
  .B Usage:
47
54
  [options]
48
55
 
49
56
  .B Options:
50
57
  .TP
51
- .B \-\-browser
52
- Open a browser to sign up and sign this CLI in, instead of printing a URL.
58
+ .B \-\-guest
59
+ Start working as an anonymous guest instead of signing up — no account or browser needed, so it works anywhere. Your work is saved to a temporary workspace you can keep later by running `postman signup`.
53
60
  .TP
54
61
  .B \-\-json
55
62
  Print the sign\-up details as machine\-readable JSON.
@@ -138,6 +145,17 @@ Show the Postman account or guest session this CLI session is using.
138
145
  .B \-\-json
139
146
  Print current identity as machine\-readable JSON.
140
147
 
148
+ .SS "update"
149
+ Update Postman CLI using the original installation method.
150
+
151
+ .B Usage:
152
+ [options]
153
+
154
+ .B Options:
155
+ .TP
156
+ .B \-\-check
157
+ Check whether a Postman CLI update is available.
158
+
141
159
  .SS "skills"
142
160
  Check and update the agent skills in this repository.
143
161
 
@@ -233,6 +251,9 @@ Run and test your Postman collections directly from the command line.
233
251
 
234
252
  .B Subcommands:
235
253
  .TP
254
+ .B collection new
255
+ Scaffold a v3 collection on disk, or create one in a cloud Postman workspace with \-\-workspace.
256
+ .TP
236
257
  .B collection migrate
237
258
  Migrate a v2.1 collection to the v3 format
238
259
  .TP
@@ -242,9 +263,50 @@ Run linting on a local v3 collection at the given file or directory path.
242
263
  .B collection ai-readiness
243
264
  Score a Postman collection for AI readiness by ID, local file path, or local\-mode directory.
244
265
  .TP
266
+ .B collection get
267
+ Fetch a Postman collection in the V3 format and print it.
268
+ .TP
269
+ .B collection list
270
+ List collections: your local project's collections by default, or a Postman cloud workspace's collections with \-\-workspace.
271
+ .TP
245
272
  .B collection run
246
273
  Initiate a Postman collection run from a given ID or path.
247
274
 
275
+ .SS "collection new"
276
+ Scaffold a v3 collection on disk, or create one in a cloud Postman workspace with \-\-workspace.
277
+
278
+ .B Usage:
279
+ <name> [options]
280
+
281
+ .B Options:
282
+ .TP
283
+ .B \-w, \-\-workspace <workspaceId>
284
+ Create the collection in a cloud Postman workspace instead of scaffolding it locally. Required when the current directory is not a local Postman workspace.
285
+ .TP
286
+ .B \-\-force
287
+ Rewrite the definition of an existing local collection. Existing request files are left alone.
288
+ .TP
289
+ .B \-\-verbose
290
+ Verbose output
291
+ .TP
292
+ .B \-\-json
293
+ JSON output
294
+
295
+ .TP Examples:
296
+
297
+ Examples:
298
+ postman collection new "Orders API"
299
+ postman collection new "Orders API" \-\-json
300
+ postman collection new "Orders API" \-\-workspace 12345678\-90ab\-cdef\-1234\-567890abcdef
301
+
302
+ Without \-\-workspace this writes postman/collections/<name>/.resources/definition.yaml
303
+ in the current directory, which must be a local Postman workspace (a directory holding
304
+ \&.postman/ or postman/). Add requests as <request\-name>.request.yaml files beside it, then
305
+ publish with `postman workspace push`. Creating a collection in a workspace requires
306
+ authentication.
307
+
308
+
309
+
248
310
  .SS "collection migrate"
249
311
  Migrate a v2.1 collection to the v3 format
250
312
 
@@ -295,6 +357,59 @@ Examples:
295
357
  Resolving a collection by ID requires authentication. Use `postman login` before running this command with a UID.
296
358
 
297
359
 
360
+ .SS "collection get"
361
+ Fetch a Postman collection in the V3 format and print it.
362
+
363
+ .B Usage:
364
+ [options] <id>
365
+
366
+ .B Options:
367
+ .TP
368
+ .B \-\-api\-key <key>
369
+ Postman API key (defaults to your `postman login` session)
370
+ .TP
371
+ .B \-\-json
372
+ Print the collection as machine\-readable V3 JSON instead of a table
373
+
374
+ .TP Examples:
375
+
376
+ Eg. postman collection get 12345\-33823532ab9e41c9b6fd12d0fd459b8b
377
+ postman collection get 0123456789abcdef01234567 \-\-json
378
+
379
+
380
+ .SS "collection list"
381
+ List collections: your local project's collections by default, or a Postman cloud workspace's collections with \-\-workspace.
382
+
383
+ .B Usage:
384
+ [options]
385
+
386
+ .B Options:
387
+ .TP
388
+ .B \-w, \-\-workspace <workspaceId>
389
+ List a Postman cloud workspace's collections by id. Omit to list the local project's collections.
390
+ .TP
391
+ .B \-f, \-\-filter <name>
392
+ Filter collections by name.
393
+ .TP
394
+ .B \-\-verbose
395
+ Verbose output
396
+ .TP
397
+ .B \-\-debug
398
+ Debug output
399
+ .TP
400
+ .B \-\-json
401
+ JSON output
402
+
403
+ .TP Examples:
404
+
405
+ Examples:
406
+ postman collection list # local project collections
407
+ postman collection list \-\-json # local, as JSON
408
+ postman collection list \-\-workspace 12345678\-90ab\-cdef\-1234\-567890abcdef # a cloud workspace
409
+ postman collection list \-\-workspace 12345678\-90ab\-cdef\-1234\-567890abcdef \-\-filter "payments"
410
+
411
+
412
+
298
413
  .SS "collection run"
299
414
  Initiate a Postman collection run from a given ID or path.
300
415
 
@@ -470,6 +585,9 @@ Work with local Postman environments from the command line. Also read cloud envi
470
585
 
471
586
  .B Subcommands:
472
587
  .TP
588
+ .B environment new
589
+ Scaffold a local environment file, or create one in a Postman workspace with \-\-workspace.
590
+ .TP
473
591
  .B environment list
474
592
  List environments in a Postman workspace.
475
593
  .TP
@@ -482,6 +600,40 @@ Read and update environment variables.
482
600
  .B environment lint
483
601
  Run linting on a local Postman environment at the given file or directory path.
484
602
 
603
+ .SS "environment new"
604
+ Scaffold a local environment file, or create one in a Postman workspace with \-\-workspace.
605
+
606
+ .B Usage:
607
+ <name> [options]
608
+
609
+ .B Options:
610
+ .TP
611
+ .B \-w, \-\-workspace <workspaceId>
612
+ Create the environment in a cloud Postman workspace instead of scaffolding it locally. Required when the current directory is not a local Postman workspace.
613
+ .TP
614
+ .B \-\-force
615
+ Overwrite an existing local environment file.
616
+ .TP
617
+ .B \-\-verbose
618
+ Verbose output
619
+ .TP
620
+ .B \-\-json
621
+ JSON output
622
+
623
+ .TP Examples:
624
+
625
+ Examples:
626
+ postman environment new Dev
627
+ postman environment new "Staging EU" \-\-json
628
+ postman environment new Dev \-\-force
629
+ postman environment new Dev \-\-workspace 12345678\-90ab\-cdef\-1234\-567890abcdef
630
+
631
+ Without \-\-workspace this writes postman/environments/<name>.environment.yaml in the
632
+ current directory, which must be a local Postman workspace (a directory holding
633
+ \&.postman/ or postman/). Creating an environment in a workspace requires authentication.
634
+
635
+
636
+
485
637
  .SS "environment list"
486
638
  List environments in a Postman workspace.
487
639
 
@@ -768,7 +920,7 @@ Eg. postman api publish <apiId> \-\-name v1\e
768
920
 
769
921
 
770
922
  .SS "runner"
771
- Where your monitors execute: run and inspect your own self\-hosted runners, and list the Postman\-operated regions available to your team
923
+ Where your monitors execute: run and inspect your own self\-hosted runners, and list the Postman\-operated regions available to your team.
772
924
 
773
925
  .B Usage:
774
926
  [options] [command]
@@ -776,16 +928,16 @@ Where your monitors execute: run and inspect your own self\-hosted runners, and
776
928
  .B Subcommands:
777
929
  .TP
778
930
  .B runner start
779
- Start a runner
931
+ Start a self\-hosted runner in your own network.
780
932
  .TP
781
933
  .B runner list
782
- List the team's registered self\-hosted runners
934
+ List the team's registered self\-hosted runners.
783
935
  .TP
784
936
  .B runner regions
785
- List the region and private\-runner values valid for monitor create/update \-\-runner, including a static IP where configured
937
+ List the region and private\-runner values valid for monitor create/update \-\-runner, with the static IP Postman runs each one from, where your team has access to it.
786
938
 
787
939
  .SS "runner start"
788
- Start a runner
940
+ Start a self\-hosted runner in your own network.
789
941
 
790
942
  .B Usage:
791
943
  [options]
@@ -799,10 +951,10 @@ The ID of the runner to execute
799
951
  The secret key for the runner
800
952
  .TP
801
953
  .B \-\-region <region>
802
- Specify the region for the runner. Use "eu" for EU region.
954
+ Region this runner reports to \-\- use "eu" for the EU region
803
955
  .TP
804
956
  .B \-\-proxy <url>
805
- External proxy URL (e.g., http://proxy.com or http://proxy.com:8080)
957
+ External proxy URL, for example http://proxy.com or http://proxy.com:8080
806
958
  .TP
807
959
  .B \-\-egress\-proxy
808
960
  Enable built\-in egress proxy
@@ -813,6 +965,9 @@ Custom egress proxy authorization service base URL
813
965
  .B \-\-ssl\-extra\-ca\-certs <path>
814
966
  Additional trusted CA certificates (PEM file, can contain multiple certs)
815
967
  .TP
968
+ .B \-\-dataset\-jdbc\-driver\-dir <path>
969
+ Folder on this machine holding the JDBC driver .jar files you put there. Required to run a dataset that uses a JDBC source. Drivers are loaded only from this folder and matched by file name; driver paths saved in the dataset are ignored
970
+ .TP
816
971
  .B \-\-metrics
817
972
  Enable the metrics server for health checks
818
973
  .TP
@@ -820,13 +975,13 @@ Enable the metrics server for health checks
820
975
  Port for the metrics server (default: 9090)
821
976
  .TP
822
977
  .B \-\-report\-events
823
- Accepted for compatibility; analytics are sent by default
978
+ Accepted for compatibility; run events are reported by default
824
979
  .TP
825
980
  .B \-\-no\-report\-events
826
- Do not send analytics to Postman
981
+ Do not report run events to Postman
827
982
 
828
983
  .SS "runner list"
829
- List the team's registered self\-hosted runners
984
+ List the team's registered self\-hosted runners.
830
985
 
831
986
  .B Usage:
832
987
  [options]
@@ -836,11 +991,14 @@ List the team's registered self\-hosted runners
836
991
  .B \-\-api\-key <key>
837
992
  Postman API key (defaults to POSTMAN_API_KEY, then the `postman login` session)
838
993
  .TP
994
+ .B \-w, \-\-workspace <id>
995
+ Filter to runners in this workspace
996
+ .TP
839
997
  .B \-\-json
840
998
  Output the runner list as JSON instead of a table
841
999
 
842
1000
  .SS "runner regions"
843
- List the region and private\-runner values valid for monitor create/update \-\-runner, including a static IP where configured
1001
+ List the region and private\-runner values valid for monitor create/update \-\-runner, with the static IP Postman runs each one from, where your team has access to it.
844
1002
 
845
1003
  .B Usage:
846
1004
  [options]
@@ -880,6 +1038,9 @@ Add, update, or remove files in a spec (cloud ID or local directory).
880
1038
  .TP
881
1039
  .B spec create
882
1040
  Create a new spec in a workspace, or (with path) scaffold a local spec file.
1041
+ .TP
1042
+ .B spec generate
1043
+ Generate artifacts from a specification.
883
1044
 
884
1045
  .SS "spec lint"
885
1046
  Run linting on the given specification by ID or local file path.
@@ -1107,6 +1268,46 @@ Examples:
1107
1268
 
1108
1269
 
1109
1270
 
1271
+ .SS "spec generate"
1272
+ Generate artifacts from a specification.
1273
+
1274
+ .B Usage:
1275
+ [options] [command]
1276
+
1277
+ .B Subcommands:
1278
+ .TP
1279
+ .B spec generate collection
1280
+ Generate a Postman collection from a specification.
1281
+
1282
+ .SS "spec generate collection"
1283
+ Generate a Postman collection from a specification.
1284
+
1285
+ .B Usage:
1286
+ [options] <spec>
1287
+
1288
+ .B Options:
1289
+ .TP
1290
+ .B \-n, \-\-name <name>
1291
+ Collection name
1292
+ .TP
1293
+ .B \-\-folder\-strategy <strategy>
1294
+ Folder strategy: Paths or Tags (default: Paths) (default: Paths)
1295
+ .TP
1296
+ .B \-w, \-\-workspace <id>
1297
+ Workspace ID (cloud mode)
1298
+ .TP
1299
+ .B \-\-api\-key <key>
1300
+ Postman API key
1301
+
1302
+ .TP Examples:
1303
+
1304
+ Examples:
1305
+ postman spec generate collection ./openapi.yaml \-n "My API"
1306
+ postman spec generate collection ./openapi.yaml \-n "My API" \-\-folder\-strategy Tags
1307
+ postman spec generate collection 12345678\-abcd\-1234\-abcd\-1234567890ab \-n "My API"
1308
+
1309
+
1310
+
1110
1311
  .SS "monitor"
1111
1312
  Run and manage Postman monitors.
1112
1313
 
@@ -1139,6 +1340,9 @@ List the monitors visible to you.
1139
1340
  .B monitor get
1140
1341
  Show a monitor's configuration.
1141
1342
  .TP
1343
+ .B monitor metrics
1344
+ Show per\-request latency and outcome history for a monitor.
1345
+ .TP
1142
1346
  .B monitor pause
1143
1347
  Pause a monitor, so it stops firing on schedule.
1144
1348
  .TP
@@ -1154,7 +1358,7 @@ Invoke a monitor run and display results.
1154
1358
  .B Options:
1155
1359
  .TP
1156
1360
  .B \-\-api\-key <key>
1157
- Postman API key (defaults to the `postman login` session)
1361
+ Postman API key (defaults to POSTMAN_API_KEY, then the `postman login` session)
1158
1362
  .TP
1159
1363
  .B \-x, \-\-suppress\-exit\-code
1160
1364
  Specify whether or not to override the default exit code for the current run
@@ -1182,7 +1386,7 @@ Collection to monitor \-\- accepts the id shown in the Postman app, prefixed or
1182
1386
  .B \-\-name <name>
1183
1387
  Monitor name (defaults to the linked collection's own name)
1184
1388
  .TP
1185
- .B \-\-environment <id>
1389
+ .B \-e, \-\-environment <id>
1186
1390
  Environment to run the monitored collection with
1187
1391
  .TP
1188
1392
  .B \-w, \-\-workspace <id>
@@ -1192,7 +1396,7 @@ Workspace to create the monitor in (defaults to the workspace named in the local
1192
1396
  Cron expression for the monitor's schedule
1193
1397
  .TP
1194
1398
  .B \-\-timezone <tz>
1195
- Time zone for \-\-schedule, e.g. America/New_York (defaults to the host machine's own zone)
1399
+ Time zone for \-\-schedule, for example America/New_York (defaults to the host machine's own zone)
1196
1400
  .TP
1197
1401
  .B \-\-runner <value>
1198
1402
  A Postman region name (see `postman runner regions`) or the id of a self\-hosted runner created in Postman (list existing ones with `postman runner list`) to run from (repeatable) (default: )
@@ -1201,10 +1405,10 @@ A Postman region name (see `postman runner regions`) or the id of a self\-hosted
1201
1405
  Email to notify on a run failure or error (repeatable) (default: )
1202
1406
  .TP
1203
1407
  .B \-\-notification\-limit <n>
1204
- Cap consecutive notifications before they are muted (service range: 1\-99)
1408
+ Consecutive failure notifications to send before muting them
1205
1409
  .TP
1206
1410
  .B \-\-retry <n>
1207
- Retries on a failed run (service caps this at 2)
1411
+ Times to retry a failed run
1208
1412
  .TP
1209
1413
  .B \-\-timeout <ms>
1210
1414
  Request timeout in milliseconds
@@ -1234,7 +1438,7 @@ Dataset view to iterate (used together with \-\-dataset\-id)
1234
1438
  Number of iterations to run
1235
1439
  .TP
1236
1440
  .B \-\-iteration\-strategy <strategy>
1237
- How iteration data is consumed, e.g. round_robin, repeat_last, stop_at_end (requires \-\-iteration\-count, \-\-dataset\-id and \-\-dataset\-view\-id)
1441
+ How iteration data is consumed, for example round_robin, repeat_last or stop_at_end (requires \-\-iteration\-count, \-\-dataset\-id and \-\-dataset\-view\-id)
1238
1442
  .TP
1239
1443
  .B \-\-no\-run\-now
1240
1444
  Do not trigger an immediate run after creating the monitor
@@ -1270,7 +1474,7 @@ New monitor name
1270
1474
  New cron expression for the monitor's schedule
1271
1475
  .TP
1272
1476
  .B \-\-timezone <tz>
1273
- Time zone for \-\-schedule, e.g. America/New_York (defaults to the host machine's own zone)
1477
+ Time zone for \-\-schedule, for example America/New_York (defaults to the host machine's own zone)
1274
1478
  .TP
1275
1479
  .B \-\-runner <value>
1276
1480
  A Postman region name (see `postman runner regions`) or the id of a self\-hosted runner created in Postman (list existing ones with `postman runner list`) to run from (repeatable; replaces the current set) (default: )
@@ -1281,11 +1485,17 @@ Email to notify on a run failure or error (repeatable; replaces the current list
1281
1485
  .B \-\-clear\-notifications
1282
1486
  Remove every notification recipient
1283
1487
  .TP
1488
+ .B \-e, \-\-environment <id>
1489
+ Environment to run the monitored collection with (replaces the current one)
1490
+ .TP
1491
+ .B \-\-clear\-environment
1492
+ Run the monitored collection with no environment
1493
+ .TP
1284
1494
  .B \-\-notification\-limit <n>
1285
- Cap consecutive notifications before they are muted (service range: 1\-99)
1495
+ Consecutive failure notifications to send before muting them
1286
1496
  .TP
1287
1497
  .B \-\-retry <n>
1288
- Retries on a failed run (service caps this at 2)
1498
+ Times to retry a failed run
1289
1499
  .TP
1290
1500
  .B \-\-timeout <ms>
1291
1501
  Request timeout in milliseconds
@@ -1315,7 +1525,7 @@ Dataset view to iterate (used together with \-\-dataset\-id)
1315
1525
  Number of iterations to run
1316
1526
  .TP
1317
1527
  .B \-\-iteration\-strategy <strategy>
1318
- How iteration data is consumed, e.g. round_robin, repeat_last, stop_at_end (requires \-\-iteration\-count, \-\-dataset\-id and \-\-dataset\-view\-id)
1528
+ How iteration data is consumed, for example round_robin, repeat_last or stop_at_end (requires \-\-iteration\-count, \-\-dataset\-id and \-\-dataset\-view\-id)
1319
1529
  .TP
1320
1530
  .B \-\-api\-key <key>
1321
1531
  Postman API key (defaults to POSTMAN_API_KEY, then the `postman login` session)
@@ -1330,8 +1540,9 @@ Examples:
1330
1540
  postman monitor update <id> \-\-notify\-email a@example.com \-\-notify\-email b@example.com
1331
1541
  postman monitor update <id> \-\-clear\-notifications
1332
1542
  postman monitor update <id> \-\-runner us\-east \-\-runner <self\-hosted\-runner\-id>
1543
+ postman monitor update <id> \-\-environment 12345678\-90ab\-cdef\-1234\-567890abcdef
1333
1544
 
1334
- This command cannot change a monitor's linked collection or environment \-\- delete and recreate the monitor instead \-\- and does not pause or resume it; use `monitor pause`/`monitor resume` for that.
1545
+ This command cannot change a monitor's linked collection \-\- that is fixed when the monitor is created, so run a different collection by creating a new monitor. It does not pause or resume a monitor either; use `monitor pause`/`monitor resume` for that.
1335
1546
 
1336
1547
 
1337
1548
  .SS "monitor delete"
@@ -1383,13 +1594,13 @@ List a monitor's recent jobs.
1383
1594
  .B Options:
1384
1595
  .TP
1385
1596
  .B \-\-api\-key <key>
1386
- Postman API key (defaults to the `postman login` session)
1597
+ Postman API key (defaults to POSTMAN_API_KEY, then the `postman login` session)
1387
1598
  .TP
1388
1599
  .B \-\-result <value>
1389
- Filter by outcome, e.g. success, failure, error, abort (server\-validated, not a fixed list)
1600
+ Filter by outcome, for example success, failure, error or abort
1390
1601
  .TP
1391
1602
  .B \-\-trigger <value>
1392
- Filter by trigger, e.g. api, schedule, webhook, postman\-cli (server\-validated, not a fixed list)
1603
+ Filter by trigger, for example api, schedule, webhook or postman\-cli
1393
1604
  .TP
1394
1605
  .B \-\-since <dateTime>
1395
1606
  Only jobs that finished at or after this ISO 8601 date\-time
@@ -1412,7 +1623,7 @@ Report one job's terminal state and its per\-region run outcomes.
1412
1623
  .B Options:
1413
1624
  .TP
1414
1625
  .B \-\-api\-key <key>
1415
- Postman API key (defaults to the `postman login` session)
1626
+ Postman API key (defaults to POSTMAN_API_KEY, then the `postman login` session)
1416
1627
  .TP
1417
1628
  .B \-\-json
1418
1629
  Output as JSON instead of a table
@@ -1437,10 +1648,10 @@ Report which test assertions ran during one attempt of a run, which failed, and
1437
1648
  .B Options:
1438
1649
  .TP
1439
1650
  .B \-\-api\-key <key>
1440
- Postman API key (defaults to the `postman login` session)
1651
+ Postman API key (defaults to POSTMAN_API_KEY, then the `postman login` session)
1441
1652
  .TP
1442
1653
  .B \-\-attempt <n>
1443
- Which attempt of the run to show, counting from 0 (default: the latest)
1654
+ Which attempt of the run to show, where 0 is the first (default: the most recent)
1444
1655
  .TP
1445
1656
  .B \-\-failed\-only
1446
1657
  Show only failed assertions
@@ -1465,11 +1676,11 @@ Filter to monitors in this workspace
1465
1676
  .B \-c, \-\-collection <id>
1466
1677
  Filter to monitors on this collection
1467
1678
  .TP
1468
- .B \-\-environment <id>
1679
+ .B \-e, \-\-environment <id>
1469
1680
  Filter to monitors on this environment
1470
1681
  .TP
1471
1682
  .B \-\-runner <id>
1472
- Filter to a Self\-Hosted Runner ID (not a Postman Region). Cannot be combined with \-\-workspace, \-\-collection, \-\-environment, \-\-owner, \-\-team or \-\-active.
1683
+ Filter to a self\-hosted runner id, not a Postman region. Cannot be combined with \-\-workspace, \-\-collection, \-\-environment, \-\-owner, \-\-team or \-\-active
1473
1684
  .TP
1474
1685
  .B \-\-owner <id>
1475
1686
  Filter to monitors created by this user id (shown in the Owner column)
@@ -1481,16 +1692,13 @@ Filter to monitors owned by your own team
1481
1692
  Filter by active state
1482
1693
  .TP
1483
1694
  .B \-\-limit <n>
1484
- Max monitors to return. The service caps page size and rejects a value above it with its own error.
1485
- .TP
1486
- .B \-\-offset <n>
1487
- Not supported: the service accepts this parameter and silently ignores it. Refused locally. Use \-\-cursor instead.
1695
+ Maximum number of monitors to return (Postman caps the page size and rejects a larger value)
1488
1696
  .TP
1489
1697
  .B \-\-cursor <token>
1490
- Pagination cursor from a previous page's response.
1698
+ Pagination cursor from a previous page's response
1491
1699
  .TP
1492
1700
  .B \-\-columns <names>
1493
- Comma\-separated columns to show. Defaults to Name, Status, ID, Schedule, Owner, Collection. Also available: State, Notifications, Environment, Runners.
1701
+ Comma\-separated columns to show. Defaults to Name, Status, ID, Schedule, Owner, Collection. Also available: State, Notifications, Environment, Runners
1494
1702
  .TP
1495
1703
  .B \-\-no\-headers
1496
1704
  Omit the header row
@@ -1534,6 +1742,40 @@ Eg. postman monitor get 12345678\-90ab\-cdef\-1234\-567890abcdef
1534
1742
  postman monitor get 12345678\-90ab\-cdef\-1234\-567890abcdef \-\-json
1535
1743
 
1536
1744
 
1745
+ .SS "monitor metrics"
1746
+ Show per\-request latency and outcome history for a monitor.
1747
+
1748
+ .B Usage:
1749
+ [options] <monitorId>
1750
+
1751
+ .B Options:
1752
+ .TP
1753
+ .B \-\-api\-key <key>
1754
+ Postman API key (defaults to POSTMAN_API_KEY, then the `postman login` session)
1755
+ .TP
1756
+ .B \-\-since <dateTime>
1757
+ Only executions at or after this ISO 8601 date\-time (defaults to 7 days ago)
1758
+ .TP
1759
+ .B \-\-until <dateTime>
1760
+ Only executions at or before this ISO 8601 date\-time (defaults to now)
1761
+ .TP
1762
+ .B \-f, \-\-filter <text>
1763
+ Show only requests whose name contains this text (case\-insensitive)
1764
+ .TP
1765
+ .B \-\-limit <n>
1766
+ Maximum number of rows to show: executions, newest first, under \-\-json, or requests, worst\-behaving first, in the table. Applied to the results after they are fetched, so it does not make the command faster
1767
+ .TP
1768
+ .B \-\-json
1769
+ Output as JSON instead of a table
1770
+
1771
+ .TP Examples:
1772
+
1773
+ Eg. postman monitor metrics 12345678\-90ab\-cdef\-1234\-567890abcdef
1774
+ postman monitor metrics 12345678\-90ab\-cdef\-1234\-567890abcdef \-\-since 2026\-09\-01T00:00:00Z
1775
+ postman monitor metrics 12345678\-90ab\-cdef\-1234\-567890abcdef \-\-filter "GET /health"
1776
+ postman monitor metrics 12345678\-90ab\-cdef\-1234\-567890abcdef \-\-json
1777
+
1778
+
1537
1779
  .SS "monitor pause"
1538
1780
  Pause a monitor, so it stops firing on schedule.
1539
1781
 
@@ -1582,6 +1824,9 @@ Push local workspace entities (collections, environments, specifications, mocks
1582
1824
  .B workspace lint
1583
1825
  Lint the current local Postman workspace: its configuration (.postman/resources.yaml) plus every discovered entity. Use \-\-meta to lint only the configuration.
1584
1826
  .TP
1827
+ .B workspace get
1828
+ Read a workspace's metadata, and optionally the ids of what it holds.
1829
+ .TP
1585
1830
  .B workspace create
1586
1831
  Create a Postman workspace and bind it to this git repository.
1587
1832
  .TP
@@ -1590,6 +1835,9 @@ Pull workspace entities from a Postman workspace into the local git\-native fold
1590
1835
  .TP
1591
1836
  .B workspace connect-git
1592
1837
  Connect a Postman workspace to a local git repository.
1838
+ .TP
1839
+ .B workspace diff
1840
+ Preview local\-vs\-cloud drift before pushing. Read\-only: nothing is created, updated or deleted.
1593
1841
 
1594
1842
  .SS "workspace list"
1595
1843
  List all available Postman Workspaces
@@ -1684,6 +1932,34 @@ The workspace ID to use for fetching governance rulesets. Defaults to the id in
1684
1932
  .B \-\-fix
1685
1933
  Apply safe autofixes to repairable workspace lint issues.
1686
1934
 
1935
+ .SS "workspace get"
1936
+ Read a workspace's metadata, and optionally the ids of what it holds.
1937
+
1938
+ .B Usage:
1939
+ [options] [id]
1940
+
1941
+ .B Options:
1942
+ .TP
1943
+ .B \-\-elements
1944
+ Also report the resources the workspace holds.
1945
+ .TP
1946
+ .B \-\-json
1947
+ Print the workspace as machine\-readable JSON.
1948
+ .TP
1949
+ .B \-\-timeout <ms>
1950
+ Milliseconds to wait for the API (default 30000).
1951
+
1952
+ .TP Examples:
1953
+
1954
+ Examples:
1955
+ postman workspace get 00a50319\-1262\-49d2\-83e5\-551e3c5dba00
1956
+ postman workspace get <id> \-\-elements
1957
+ postman workspace get <id> \-\-json
1958
+
1959
+ Exit codes: 0 ok, 1 not found or API failure, 2 bad usage, 3 auth.
1960
+
1961
+
1962
+
1687
1963
  .SS "workspace create"
1688
1964
  Create a Postman workspace and bind it to this git repository.
1689
1965
 
@@ -1774,6 +2050,46 @@ Examples:
1774
2050
 
1775
2051
 
1776
2052
 
2053
+ .SS "workspace diff"
2054
+ Preview local\-vs\-cloud drift before pushing. Read\-only: nothing is created, updated or deleted.
2055
+
2056
+ .B Usage:
2057
+ [options] [workspaceId]
2058
+
2059
+ .B Options:
2060
+ .TP
2061
+ .B \-\-push\-strategy <strategy>
2062
+ Strategy to preview. "force\-sync" also shows cloud entities that would be DELETED. Defaults to "force\-sync".
2063
+ .TP
2064
+ .B \-\-summary
2065
+ Skip content comparison. Faster, but updates are listed without checking whether they changed.
2066
+ .TP
2067
+ .B \-\-json
2068
+ Print the diff as machine\-readable JSON.
2069
+ .TP
2070
+ .B \-\-exit\-code
2071
+ Exit with code 1 when drift is found (for CI gates).
2072
+ .TP
2073
+ .B \-\-verbose
2074
+ Show detailed logging
2075
+ .TP
2076
+ .B \-\-timeout <ms>
2077
+ Abort the run after this many milliseconds. Defaults to 120000.
2078
+
2079
+ .TP Examples:
2080
+
2081
+ Examples:
2082
+ postman workspace diff
2083
+ Preview what `push \-\-push\-strategy force\-sync` would do
2084
+ postman workspace diff \-\-summary
2085
+ Fast deletion preview, no content comparison
2086
+ postman workspace diff \-\-json \-\-exit\-code
2087
+ Machine\-readable output, exit 1 when there is drift (CI gate)
2088
+ postman workspace diff \-\-push\-strategy default
2089
+ Preview a create/update\-only push, hiding deletions
2090
+
2091
+
2092
+
1777
2093
  .SS "performance"
1778
2094
  Manage performance tests on your collections.
1779
2095
 
@@ -1784,6 +2100,9 @@ Manage performance tests on your collections.
1784
2100
  .TP
1785
2101
  .B performance run
1786
2102
  Run a performance test on a collection
2103
+ .TP
2104
+ .B performance list
2105
+ List past performance runs for a collection, newest first.
1787
2106
 
1788
2107
  .SS "performance run"
1789
2108
  Run a performance test on a collection
@@ -1851,6 +2170,40 @@ Examples:
1851
2170
  postman performance run 123456\-45159473\-1e45\-1f34\-5678\-1234567890ab \-\-runner postman\-cloud\-static\-ip
1852
2171
 
1853
2172
 
2173
+ .SS "performance list"
2174
+ List past performance runs for a collection, newest first.
2175
+
2176
+ .B Usage:
2177
+ \-\-collection\-id <id> [options]
2178
+
2179
+ .B Options:
2180
+ .TP
2181
+ .B \-c, \-\-collection\-id <id>
2182
+ Collection ID whose performance runs to list
2183
+ .TP
2184
+ .B \-\-cursor <token>
2185
+ Pagination cursor from a previous page's response
2186
+ .TP
2187
+ .B \-\-json
2188
+ Output as JSON instead of a table
2189
+ .TP
2190
+ .B \-\-timeout <ms>
2191
+ Milliseconds to wait for the service before failing (default: 30000)
2192
+
2193
+ .TP Examples:
2194
+
2195
+ Examples:
2196
+ postman performance list \-\-collection\-id 1402295\-45159473\-1e45\-1f34\-5678\-1234567890ab
2197
+ postman performance list \-c 1402295\-45159473\-1e45\-1f34\-5678\-1234567890ab \-\-json
2198
+ postman performance list \-c 1402295\-45159473\-1e45\-1f34\-5678\-1234567890ab \-\-cursor eyJpZCI6...
2199
+
2200
+ The newest 25 runs are returned. A `\-` in Duration means the run has not finished yet.
2201
+ A page shorter than 25 does not mean the end of the list: use the printed \-\-cursor
2202
+ while one is offered.
2203
+
2204
+ Authentication uses POSTMAN_API_KEY, or the `postman login` session.
2205
+
2206
+
1854
2207
  .SS "flows"
1855
2208
  Manage and interact with flows.
1856
2209
 
@@ -2916,7 +3269,7 @@ Turn a mock in Postman cloud into a live mock server others can call over the in
2916
3269
  Show a mock's details using its path if it lives in your repository, or its id if it lives in Postman cloud.
2917
3270
  .TP
2918
3271
  .B mock list
2919
- List the mocks in your Postman cloud workspace, or — with a folder path — the mocks in that folder in your repository.
3272
+ List the mocks in your repository or Postman cloud workspace
2920
3273
  .TP
2921
3274
  .B mock log
2922
3275
  Show the requests a live mock server has received and the responses it sent, using its id.
@@ -3088,7 +3441,7 @@ Paths can be relative (e.g. ./postman/mocks/orders) or absolute (e.g. /Users/me/
3088
3441
 
3089
3442
 
3090
3443
  .SS "mock list"
3091
- List the mocks in your Postman cloud workspace, or — with a folder path — the mocks in that folder in your repository.
3444
+ List the mocks in your repository or Postman cloud workspace
3092
3445
 
3093
3446
  .B Usage:
3094
3447
  [pathOrDir] [options]
@@ -4547,6 +4900,9 @@ Inspect and manage a dataset's datasources.
4547
4900
  .TP
4548
4901
  .B dataset view
4549
4902
  Inspect and manage saved views on a dataset.
4903
+ .TP
4904
+ .B dataset jdbc
4905
+ Inspect JDBC drivers before attaching one to a dataset.
4550
4906
 
4551
4907
  .SS "dataset list"
4552
4908
  List local dataset YAMLs under a path, or (no path) a workspace's cloud datasets.
@@ -4719,6 +5075,9 @@ Remove a datasource from a dataset (local YAML path or cloud id).
4719
5075
  .TP
4720
5076
  .B dataset source update
4721
5077
  Update fields on an existing datasource. Only the flags you provide are changed.
5078
+ .TP
5079
+ .B dataset source test
5080
+ Open and close a real connection using a source's stored configuration.
4722
5081
 
4723
5082
  .SS "dataset source list"
4724
5083
  List the datasources defined on a dataset (local YAML path or cloud id).
@@ -4765,8 +5124,8 @@ Override the generated source id (local dataset only)
4765
5124
  .B \-\-format <csv|json|mysql|postgres|sqlserver>
4766
5125
  Use this format instead of extension/type inference; file contents are not sniffed
4767
5126
  .TP
4768
- .B \-\-type <local|mysql|postgresql|sqlserver>
4769
- Source kind; local is inferred when \-\-file is provided
5127
+ .B \-\-type <local|mysql|postgresql|sqlserver|jdbc>
5128
+ Source kind; local is inferred from \-\-file, jdbc from \-\-driver\-jar
4770
5129
  .TP
4771
5130
  .B \-\-file <path>
4772
5131
  Path to a local CSV/JSON file (absolute or cwd\-relative)
@@ -4780,6 +5139,45 @@ When copying, overwrite an existing file at the destination (local dataset)
4780
5139
  .B \-\-upload
4781
5140
  Cloud dataset only: upload \-\-file as a postmancloudfile source (runs via /exec). Without \-\-upload, \-\-file is registered as a local_filesystem csv/json source read by the local engine.
4782
5141
  .TP
5142
+ .B \-\-driver\-jar <path...>
5143
+ JDBC driver JAR(s). Repeatable, or pass several after one flag
5144
+ .TP
5145
+ .B \-\-driver\-class <fqcn>
5146
+ Driver class. Auto\-resolved when the JAR contains exactly one
5147
+ .TP
5148
+ .B \-\-driver\-name <label>
5149
+ Label for this driver type (defaults to the JAR filename)
5150
+ .TP
5151
+ .B \-\-url\-template <template>
5152
+ JDBC URL with {{placeholders}}, e.g. jdbc:postgresql://{{host}}:{{port}}/{{database}}
5153
+ .TP
5154
+ .B \-\-var <name=value...>
5155
+ Value for a {{placeholder}}. Repeatable. Use vault:<vaultId>/<secretId> for a secret. WARNING: a literal value is visible in `ps` output and shell history, and is stored in clear text in the dataset YAML (local) or sent in the request body (cloud). Prefer a Shared Vault reference.
5156
+ .TP
5157
+ .B \-\-prop <name=value...>
5158
+ Driver connection property. Repeatable. Same vault: syntax as \-\-var
5159
+ .TP
5160
+ .B \-\-vars\-file <path>
5161
+ JSON object of \-\-var values; "\-" reads stdin. Supports {"$vaultId":..,"$secretId":..} objects, and keeps secrets out of argv entirely
5162
+ .TP
5163
+ .B \-\-from\-source <name>
5164
+ Reuse another source's driver JAR, class and URL template
5165
+ .TP
5166
+ .B \-\-java\-path <path>
5167
+ Java runtime to use. Machine\-local only \- never written to the dataset. Also read from POSTMAN_JDBC_JAVA_PATH
5168
+ .TP
5169
+ .B \-\-no\-test
5170
+ Skip the pre\-write connection test. Note that resolving the driver class still starts a JVM — on a machine with no Java, pass \-\-driver\-class (or \-\-from\-source) too
5171
+ .TP
5172
+ .B \-\-ssh\-target\-host\-variable <name>
5173
+ Template variable holding the tunnelled host (inferred when omitted)
5174
+ .TP
5175
+ .B \-\-ssh\-target\-port\-variable <name>
5176
+ Template variable holding the tunnelled port (inferred when omitted)
5177
+ .TP
5178
+ .B \-\-json
5179
+ Emit the result as JSON instead of prose
5180
+ .TP
4783
5181
  .B \-\-host <host>
4784
5182
  DB host (mysql/postgresql/sqlserver)
4785
5183
  .TP
@@ -4787,10 +5185,10 @@ DB host (mysql/postgresql/sqlserver)
4787
5185
  DB port (defaults to 1433 for sqlserver)
4788
5186
  .TP
4789
5187
  .B \-\-user <user>
4790
- DB user (warning: stored as plaintext in the YAML).
5188
+ DB user. WARNING: a literal value is visible in `ps` output and shell history, and is stored in clear text in the dataset YAML (local) or sent in the request body (cloud). Prefer a Shared Vault reference.
4791
5189
  .TP
4792
5190
  .B \-\-password <password>
4793
- DB password. WARNING: passing it here exposes it in `ps` output and shell history, and it is stored as plaintext in the dataset YAML (local) or sent in the request body (cloud). Prefer a restricted DB user; secure input (prompt / stdin / env) is planned.
5191
+ DB password. WARNING: a literal value is visible in `ps` output and shell history, and is stored in clear text in the dataset YAML (local) or sent in the request body (cloud). Prefer a Shared Vault reference.
4794
5192
  .TP
4795
5193
  .B \-\-database <db>
4796
5194
  DB database name
@@ -4857,6 +5255,60 @@ Format selection:
4857
5255
  Execution:
4858
5256
  \-\-upload runs file\-backed queries in the cloud service. Without \-\-upload, the local engine reads the file.
4859
5257
 
5258
+ JDBC:
5259
+ Start with `postman dataset jdbc inspect <jar>`. Its output maps onto these
5260
+ flags directly: suggestedUrlTemplate \-> \-\-url\-template, templateVariables \->
5261
+ \-\-var, connectionProperties \-> \-\-prop, driverClass \-> \-\-driver\-class.
5262
+
5263
+ postman dataset jdbc inspect ./drivers/postgresql\-42.7.4.jar
5264
+ postman dataset source add \-d ./orders.dataset.yaml \-n orders \-\-type jdbc \e
5265
+ \-\-driver\-jar ./drivers/postgresql\-42.7.4.jar \e
5266
+ \-\-url\-template 'jdbc:postgresql://{{host}}:{{port}}/{{database}}' \e
5267
+ \-\-var host=db.internal \-\-var port=5432 \-\-var database=shop \e
5268
+ \-\-var user=vault:acme/pg\-user \-\-var password=vault:acme/pg\-pass
5269
+
5270
+ Reuse that driver for a second source, no rediscovery needed:
5271
+ postman dataset source add \-d ./orders.dataset.yaml \-n refunds \-\-type jdbc \e
5272
+ \-\-from\-source orders \-\-var host=db.internal \-\-var port=5432 \-\-var database=refunds
5273
+
5274
+ Secrets:
5275
+ \-\-var <k>=vault:<vaultId>/<secretId> reference a Shared Vault secret (preferred)
5276
+ \-\-var <k>=<literal> plaintext: visible in `ps` output and shell
5277
+ history, and stored in clear text in the
5278
+ dataset YAML. Warned about at run time.
5279
+ A secret written directly into \-\-url\-template is rejected: a literal has no
5280
+ {{name}} to route through \-\-var, so it can never be a Vault reference and
5281
+ nothing masks it. Use a placeholder plus \-\-var instead.
5282
+ \-\-vars\-file <path|\-> JSON object; "\-" reads stdin, keeping
5283
+ secrets out of argv entirely. Accepts
5284
+ {"$vaultId":..,"$secretId":..} values.
5285
+ Local Vault secrets are not supported by Postman CLI; use a Shared Vault.
5286
+
5287
+ Connection test:
5288
+ Runs before the source is written, so a source that cannot connect is never
5289
+ persisted. Needs a local JRE and a loadable driver. Pass \-\-no\-test to skip it.
5290
+ \-\-no\-test alone still needs Java to resolve the driver class; on a machine with
5291
+ no Java at all, add \-\-driver\-class or \-\-from\-source so nothing has to load it.
5292
+
5293
+ JSON output (\-\-json):
5294
+ Success: {"ok":true,"source":{"id","name","target","format","driver",
5295
+ "urlTemplate","connectionTest"},"warnings":[...]}
5296
+ Failure: {"ok":false,"error":{"code","message","remediation",...context}}
5297
+ Both go to stdout, so `\-\-json 2>/dev/null | jq .` parses either way.
5298
+ Error codes: DRIVER_FILE_NOT_FOUND, DRIVER_CLASS_NOT_FOUND,
5299
+ DRIVER_CLASS_AMBIGUOUS (with candidates[]), URL_TEMPLATE_INVALID,
5300
+ CONFIG_VALUE_MISSING (with missing[]), URL_TEMPLATE_LITERAL_SECRET,
5301
+ VAULT_REFERENCE_INVALID,
5302
+ VARS_FILE_UNREADABLE, VARS_FILE_INVALID, SOURCE_NOT_FOUND, SOURCE_NOT_JDBC,
5303
+ JAVA_NOT_FOUND, JAVA_UNSUPPORTED, DRIVER_LOAD_FAILED, CONNECTION_FAILED,
5304
+ CONNECTION_TIMEOUT, SECRET_RESOLUTION_FAILED, INVALID_ARGUMENT
5305
+ Warning codes: PLAINTEXT_SECRET, CONNECTION_NOT_TESTED, NO_VARIABLES,
5306
+ EMPTY_VARIABLE_VALUE, NAME_NOT_SQL_SAFE, TRUST_SERVER_CERTIFICATE,
5307
+ SSH_VALUES_IN_ARGV, SSH_HOST_KEY_UNVERIFIED
5308
+ LOCAL_VAULT_UNSUPPORTED, SOURCE_NAME_CONFLICT, SOURCE_ID_CONFLICT and
5309
+ DATASET_FILE_CHANGED are also possible; DATASET_COMMAND_FAILED is the
5310
+ fallback for anything unclassified.
5311
+
4860
5312
 
4861
5313
 
4862
5314
  .SS "dataset source remove"
@@ -4908,6 +5360,42 @@ With \-\-file, reference in place instead of copying (local dataset only)
4908
5360
  .B \-\-force
4909
5361
  With \-\-file, overwrite the copied destination (local dataset only)
4910
5362
  .TP
5363
+ .B \-\-driver\-jar <path...>
5364
+ Replace the JDBC driver JAR(s)
5365
+ .TP
5366
+ .B \-\-driver\-class <fqcn>
5367
+ Replace the JDBC driver class
5368
+ .TP
5369
+ .B \-\-driver\-name <label>
5370
+ Rename the JDBC driver type label
5371
+ .TP
5372
+ .B \-\-url\-template <template>
5373
+ Replace the JDBC URL template
5374
+ .TP
5375
+ .B \-\-var <name=value...>
5376
+ Set a JDBC template variable. Merges onto the existing values. Use vault:<vaultId>/<secretId> for a secret. WARNING: a literal value is visible in `ps` output and shell history, and is stored in clear text in the dataset YAML (local) or sent in the request body (cloud). Prefer a Shared Vault reference.
5377
+ .TP
5378
+ .B \-\-prop <name=value...>
5379
+ Set a JDBC connection property. Merges, same vault: syntax
5380
+ .TP
5381
+ .B \-\-unset\-var <name...>
5382
+ Remove a JDBC template variable. Merging alone can never remove a key
5383
+ .TP
5384
+ .B \-\-unset\-prop <name...>
5385
+ Remove a JDBC connection property
5386
+ .TP
5387
+ .B \-\-vars\-file <path>
5388
+ JSON object of \-\-var values; "\-" reads stdin
5389
+ .TP
5390
+ .B \-\-ssh\-target\-host\-variable <name>
5391
+ Template variable holding the tunnelled host (JDBC)
5392
+ .TP
5393
+ .B \-\-ssh\-target\-port\-variable <name>
5394
+ Template variable holding the tunnelled port (JDBC)
5395
+ .TP
5396
+ .B \-\-java\-path <path>
5397
+ Java runtime for JDBC operations. Machine\-local only
5398
+ .TP
4911
5399
  .B \-\-host <host>
4912
5400
  Update DB host (mysql/postgresql/sqlserver)
4913
5401
  .TP
@@ -4915,10 +5403,10 @@ Update DB host (mysql/postgresql/sqlserver)
4915
5403
  Update DB port
4916
5404
  .TP
4917
5405
  .B \-\-user <user>
4918
- Update DB user (warning: stored as plaintext in the YAML).
5406
+ Update DB user. WARNING: a literal value is visible in `ps` output and shell history, and is stored in clear text in the dataset YAML (local) or sent in the request body (cloud). Prefer a Shared Vault reference.
4919
5407
  .TP
4920
5408
  .B \-\-password <password>
4921
- Update DB password. WARNING: passing it here exposes it in `ps` output and shell history, and it is stored as plaintext in the dataset YAML (local) or sent in the request body (cloud). Prefer a restricted DB user; secure input (prompt / stdin / env) is planned.
5409
+ Update DB password. WARNING: a literal value is visible in `ps` output and shell history, and is stored in clear text in the dataset YAML (local) or sent in the request body (cloud). Prefer a Shared Vault reference.
4922
5410
  .TP
4923
5411
  .B \-\-database <db>
4924
5412
  Update DB database name
@@ -4970,6 +5458,9 @@ Update SQL Server minimum TLS version
4970
5458
  .TP
4971
5459
  .B \-\-api\-key <key>
4972
5460
  Postman API key (defaults to the `postman login` session)
5461
+ .TP
5462
+ .B \-\-json
5463
+ Emit the result as JSON instead of prose
4973
5464
 
4974
5465
  .TP Examples:
4975
5466
 
@@ -4979,6 +5470,73 @@ Examples:
4979
5470
  postman dataset source update orders\-db \e
4980
5471
  \-d 14e30f6c\-1234\-1234\-1234\-cafef00dc0de \-\-host db.internal.example
4981
5472
 
5473
+ JDBC:
5474
+ Rotate one credential, leaving everything else alone:
5475
+ postman dataset source update orders \-d ./orders.dataset.yaml \e
5476
+ \-\-var password=vault:acme/pg\-pass\-2024\-11
5477
+
5478
+ Remove a variable the template no longer uses:
5479
+ postman dataset source update orders \-d ./orders.dataset.yaml \e
5480
+ \-\-url\-template 'jdbc:postgresql://{{host}}:{{port}}/{{database}}' \-\-unset\-var schema
5481
+
5482
+ Merge semantics: \-\-var and \-\-prop add to what is already stored, so you need
5483
+ not restate the whole connection. \-\-unset\-var and \-\-unset\-prop exist because
5484
+ merging alone can never remove a key. The template is validated against the
5485
+ MERGED values, so removing one the URL still needs fails here rather than at
5486
+ connect time.
5487
+
5488
+ Run `postman dataset source test \-d <dataset> \-n <name>` afterwards to check
5489
+ the change actually connects.
5490
+
5491
+
5492
+
5493
+ .SS "dataset source test"
5494
+ Open and close a real connection using a source's stored configuration.
5495
+
5496
+ .B Usage:
5497
+ [options]
5498
+
5499
+ .B Options:
5500
+ .TP
5501
+ .B \-d, \-\-dataset <datasetPathOrId>
5502
+ Dataset the source belongs to — a local .dataset.yaml path or a cloud dataset id
5503
+ .TP
5504
+ .B \-n, \-\-name <name>
5505
+ Source to test
5506
+ .TP
5507
+ .B \-\-java\-path <path>
5508
+ Java runtime to use for a JDBC source. Machine\-local only; also read from POSTMAN_JDBC_JAVA_PATH
5509
+ .TP
5510
+ .B \-\-api\-key <key>
5511
+ Postman API key (defaults to the `postman login` session)
5512
+ .TP
5513
+ .B \-\-json
5514
+ Emit the result as JSON instead of prose
5515
+
5516
+ .TP Examples:
5517
+
5518
+ Examples:
5519
+ postman dataset source test \-d ./orders.dataset.yaml \-n orders
5520
+ postman dataset source test \-d 14e30f6c\-1234\-1234\-1234\-cafef00dc0de \-n orders \-\-json
5521
+
5522
+ What it is for:
5523
+ When a query fails, this separates "the source is broken" from "the SQL is
5524
+ wrong". It uses the stored configuration, resolving any Vault references the
5525
+ same way a real query would.
5526
+
5527
+ Applies to database and JDBC sources. File and URL sources have no connection
5528
+ to test and report SOURCE_NOT_TESTABLE.
5529
+
5530
+ JSON output (\-\-json):
5531
+ Success: {"ok":true,"source":{"name","format"},"connectionTest":{"status":"passed"},
5532
+ "warnings":[]}
5533
+ Failure: {"ok":false,"error":{"code","message","remediation"}}
5534
+ Both go to stdout, so `\-\-json 2>/dev/null | jq .` parses either way.
5535
+ Error codes: SOURCE_NOT_FOUND (with available[]), SOURCE_NOT_TESTABLE,
5536
+ SOURCE_NOT_JDBC, SOURCE_CONFIG_UNAVAILABLE, CONNECTION_FAILED,
5537
+ CONN_AUTH_FAILED, CONNECTION_TIMEOUT, JAVA_NOT_FOUND, DRIVER_LOAD_FAILED,
5538
+ HOST_PROTOCOL_ERROR, SECRET_RESOLUTION_FAILED, DATASET_COMMAND_FAILED
5539
+
4982
5540
 
4983
5541
 
4984
5542
  .SS "dataset view"
@@ -5080,9 +5638,15 @@ View name
5080
5638
  .B \-q, \-\-query <sql>
5081
5639
  SQL query the view executes
5082
5640
  .TP
5641
+ .B \-s, \-\-source <nameOrIdOrSlug>
5642
+ Bind the view to one datasource and run the query natively against it, instead of through the federated SQLite layer. Same reference `dataset query \-s` takes
5643
+ .TP
5083
5644
  .B \-\-view\-id <uuid>
5084
5645
  Override the generated view id (local only; cloud assigns its own)
5085
5646
  .TP
5647
+ .B \-\-json
5648
+ Emit the result as JSON instead of prose
5649
+ .TP
5086
5650
  .B \-\-api\-key <key>
5087
5651
  Postman API key (defaults to the `postman login` session)
5088
5652
 
@@ -5094,6 +5658,22 @@ Examples:
5094
5658
  postman dataset view create \-d 14e30f6c\-1234\-1234\-1234\-cafef00dc0de \e
5095
5659
  \-n "Active Users" \-q "SELECT * FROM users WHERE active = true"
5096
5660
 
5661
+ Native view against one source (JDBC, MySQL, Postgres, SQL Server):
5662
+ postman dataset view create \-d ./orders.dataset.yaml \-n recent \e
5663
+ \-\-source orders \-q "SELECT * FROM orders WHERE created_at > now() \- interval '1 day'"
5664
+
5665
+ Federated vs native:
5666
+ Without \-\-source the query runs through the federated SQLite layer and can
5667
+ join across sources. With \-\-source it is sent to that one datasource in its
5668
+ own SQL dialect, which is what JDBC sources need. Mirrors `dataset query \-s`.
5669
+
5670
+ JSON output (\-\-json):
5671
+ Success: {"ok":true,"view":{"id","name","target","datasourceId","viewType"},
5672
+ "warnings":[]}
5673
+ Failure: {"ok":false,"error":{"code","message","remediation"}}
5674
+ Error codes: SOURCE_NOT_FOUND (with available[]), DATASET_FILE_CHANGED,
5675
+ DATASET_FILE_UNWRITABLE, DATASET_COMMAND_FAILED
5676
+
5097
5677
 
5098
5678
 
5099
5679
  .SS "dataset view delete"
@@ -5148,6 +5728,71 @@ Examples:
5148
5728
 
5149
5729
 
5150
5730
 
5731
+ .SS "dataset jdbc"
5732
+ Inspect JDBC drivers before attaching one to a dataset.
5733
+
5734
+ .B Usage:
5735
+ [options] [command]
5736
+
5737
+ .B Subcommands:
5738
+ .TP
5739
+ .B dataset jdbc inspect
5740
+ Detect Java, list driver classes, suggest a URL template and read driver properties.
5741
+
5742
+ .SS "dataset jdbc inspect"
5743
+ Detect Java, list driver classes, suggest a URL template and read driver properties.
5744
+
5745
+ .B Usage:
5746
+ [options] [jar...]
5747
+
5748
+ .B Options:
5749
+ .TP
5750
+ .B \-\-driver\-class <fqcn>
5751
+ Introspect this class instead of auto\-selecting
5752
+ .TP
5753
+ .B \-\-url\-template <template>
5754
+ Use this URL template instead of the one inferred from the JAR filename
5755
+ .TP
5756
+ .B \-\-java\-path <path>
5757
+ Java runtime to use. Machine\-local only — never written to a dataset. Also read from POSTMAN_JDBC_JAVA_PATH.
5758
+ .TP
5759
+ .B \-\-json
5760
+ Emit the discovery result as JSON
5761
+
5762
+ .TP Examples:
5763
+
5764
+ Examples:
5765
+ postman dataset jdbc inspect ./drivers/postgresql\-42.7.3.jar
5766
+ postman dataset jdbc inspect ./drivers/mysql\-connector\-j\-8.4.0.jar \-\-json
5767
+ postman dataset jdbc inspect ./a.jar ./b.jar \-\-driver\-class com.acme.Driver
5768
+
5769
+ What it reports:
5770
+ The Java runtime it found, every java.sql.Driver class in the artifacts,
5771
+ a suggested URL template, that template's {{variables}}, and the
5772
+ connection properties the driver accepts.
5773
+
5774
+ Feeding the result into `source add`:
5775
+ suggestedUrlTemplate \-> \-\-url\-template
5776
+ templateVariables[] \-> \-\-var <name>=<value>
5777
+ connectionProperties[] \-> \-\-prop <name>=<value>
5778
+ driverClass \-> \-\-driver\-class (only needed when ambiguous)
5779
+
5780
+ JSON output (\-\-json):
5781
+ Success: {"ok":true,"java":{...},"drivers":[...],"suggestedUrlTemplate":"...",
5782
+ "templateVariables":[...],"connectionProperties":[...],"warnings":[...]}
5783
+ Failure: {"ok":false,"error":{"code":...,"message":...,"remediation":...}}
5784
+ Error codes: JAVA_NOT_FOUND, JAVA_UNSUPPORTED, DRIVER_FILE_NOT_FOUND,
5785
+ DRIVER_FILE_UNREADABLE, DRIVER_INCOMPATIBLE, DRIVER_LOAD_FAILED,
5786
+ DRIVER_CLASS_NOT_FOUND, URL_TEMPLATE_INVALID, HOST_START_FAILED
5787
+ Warning codes: DRIVER_CLASS_AMBIGUOUS, DRIVER_PROPERTIES_EMPTY,
5788
+ DRIVER_PROPERTIES_UNAVAILABLE, URL_TEMPLATE_INVALID
5789
+ `minimumJavaMajorVersion` is present when the artifacts declare one.
5790
+
5791
+ Several driver classes in one JAR is reported, not an error. Re\-run with
5792
+ \-\-driver\-class to read that driver's connection properties.
5793
+
5794
+
5795
+
5151
5796
  .SS "dependency"
5152
5797
  Manage workspace dependencies (Postman entities reused from other workspaces).
5153
5798
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "postman-cli",
3
- "version": "1.58.0",
3
+ "version": "1.60.0",
4
4
  "description": "Official Postman CLI - Command-line companion for API development, testing, and automation",
5
5
  "keywords": [
6
6
  "postman",
@@ -58,10 +58,10 @@
58
58
  "man/"
59
59
  ],
60
60
  "optionalDependencies": {
61
- "@postman/pm-bin-macos-arm64": "1.58.0",
62
- "@postman/pm-bin-macos-x64": "1.58.0",
63
- "@postman/pm-bin-linux-x64": "1.58.0",
64
- "@postman/pm-bin-linux-arm64": "1.58.0",
65
- "@postman/pm-bin-windows-x64": "1.58.0"
61
+ "@postman/pm-bin-macos-arm64": "1.60.0",
62
+ "@postman/pm-bin-macos-x64": "1.60.0",
63
+ "@postman/pm-bin-linux-x64": "1.60.0",
64
+ "@postman/pm-bin-linux-arm64": "1.60.0",
65
+ "@postman/pm-bin-windows-x64": "1.60.0"
66
66
  }
67
67
  }