Postman CLI dataset commands `(postman dataset)`

This topic covers dataset commands for the Postman CLI.

Datasets enable you to define reusable data sources and views for use in Postman workflows. You can use dataset commands to create and manage datasets, configure data sources, run SQL queries, and run saved views.

Each dataset command works with either a local dataset file or a cloud dataset stored in a Postman workspace:

Local — Specify the path to a .dataset.yaml file.
Cloud — Specify the dataset’s ID.

A dataset stores a definition, not your data: where the data lives, what each source is named, and the SQL that shapes your views. It doesn’t copy your rows into the manifest, which is why a .dataset.yaml file stays small.

A view stores only its query. Rows are recomputed from the source each time you run it.
A source is a pointer to your data: a database connection or a file path. Two cases store a copy instead:
- Adding a local file copies it into a .resources/ folder next to the dataset.
- Uploading a file to a cloud dataset stores the file in Postman.

To run a collection with a dataset or a saved view, use the --iteration-data-dataset, --iteration-data-view, and --dataset options with the postman collection run command. To learn more, see Collection commands.

Commands that work with a cloud dataset authenticate with your postman login session by default. To authenticate a single command with a specific Postman API key instead, pass the --api-key <key> option:

--api-key <key>

A Postman API key used to authenticate a cloud dataset command, instead of your postman login session.

`postman dataset create`

Creates a new dataset.

To use this command with a cloud dataset, sign in to Postman with the postman login command, or pass the --api-key <key> option to use a specific API key.

Usage

postman dataset create [local-dataset-path] [options]

[local-dataset-path]

To create a local dataset file, provide the path where you want to create it. To create a cloud dataset, omit this argument and use the -w, --workspace option instead.

Options

-n, --name <name>

Required

The dataset name.

-d, --description <description>

A description for the dataset.

--dataset-id <uuid>

Defaults to Random v4 UUID

(Local only) Unique identifier for the dataset. If not provided, a random v4 UUID is generated. A cloud dataset assigns its own ID.

-w, --workspace <id>

The Postman workspace ID in which to create a cloud dataset.

--force

Overwrites an existing dataset file.

Examples

postman dataset create ./postman/datasets/customers.dataset.yaml \
  -n "Customer Data"
postman dataset create \
  -w 12345678-90ab-cdef-1234-567890abcdef \
  -n "Customer Data"

`postman dataset list`

Lists datasets.

To use this command with a cloud dataset, sign in to Postman with the postman login command, or pass the --api-key <key> option to use a specific API key.

Usage

postman dataset list [local-dataset-path] [options]

[local-dataset-path]

To list local datasets, provide the path to a dataset file or a directory that contains one or more dataset files. To list cloud datasets, omit this argument and use the -w, --workspace option instead.

Options

-w, --workspace <id>

The Postman workspace ID whose cloud datasets you want to list.

--json

Displays results in JSON format.

Examples

postman dataset list ./postman/datasets
postman dataset list ./postman/datasets/customers.dataset.yaml
postman dataset list -w 12345678-90ab-cdef-1234-567890abcdef

`postman dataset get`

Displays metadata and a structure summary for a dataset.

To use this command with a cloud dataset, sign in to Postman with the postman login command, or pass the --api-key <key> option to use a specific API key.

Usage

postman dataset get <dataset-path-or-id> [options]

<dataset-path-or-id>

Path to a local dataset file or a cloud dataset ID.

Options

--no-populate

(Cloud only) Skips fetching the dataset’s data sources and views, returning only its top-level metadata. If you don’t need the full structure, this can help make the command faster.

--json

Displays results in JSON format.

Examples

postman dataset get ./postman/datasets/customers.dataset.yaml
postman dataset get 14e30f6c-1234-1234-1234-cafef00dc0de

`postman dataset query`

Runs a SQL query against a dataset.

To use this command with a cloud dataset, sign in to Postman with the postman login command, or pass the --api-key <key> option to use a specific API key.

Usage

postman dataset query <dataset-path-or-id> [options]

<dataset-path-or-id>

Path to a local dataset file or a cloud dataset ID.

Options

-q, --query <query>

Required

The SQL query to run.

-p, --param <parameter>

Provides a value for a positional placeholder in the query. The first -p value fills $1, the second fills $2, and so on. Repeat the option to pass multiple values, for example -p value1 -p value2.

--json

Displays query results in JSON format.

--debug

Shows detailed debug output for the query.

Examples

postman dataset query ./postman/datasets/customers.dataset.yaml \
  -q "SELECT * FROM customers LIMIT 10"
postman dataset query ./postman/datasets/customers.dataset.yaml \
  -q "SELECT * FROM customers WHERE id = $1" \
  -p 42
postman dataset query 14e30f6c-1234-1234-1234-cafef00dc0de \
  -q "SELECT * FROM customers LIMIT 10"

`postman dataset jdbc`

Inspect a JDBC driver before you attach it to a dataset.

`postman dataset jdbc inspect`

Reports what a JDBC driver JAR contains, so you know what to pass when you add a custom data source. The command detects your Java runtime, lists every driver class in the JAR, suggests a URL template, lists that template’s variables, and lists the connection properties the driver accepts.

Java 8 or newer must be installed on the computer running the command.

Usage

postman dataset jdbc inspect [jar...]

[jar...]

Path to one or more JDBC driver JAR files to inspect. List a dependency JAR’s path after the primary driver JAR when the driver needs it to resolve classes.

Options

--driver-class <fqcn>

Inspects this driver class instead of selecting one automatically. Use it when the JAR contains more than one driver class.

--url-template <template>

Reports variables for this URL template instead of the one inferred from the JAR file name.

--java-path <path>

The Java runtime to use. This value stays on your computer and is never written to a dataset. Also read from the POSTMAN_JDBC_JAVA_PATH environment variable.

--json

Returns the result as JSON instead of prose.

Examples

Inspect a driver JAR:

postman dataset jdbc inspect ./drivers/postgresql-42.7.3.jar

Inspect a driver that has several dependency JAR files:

postman dataset jdbc inspect ./drivers/a.jar ./drivers/b.jar

The report maps directly onto the options you pass to postman dataset source add:

The report’s field	The option to pass
`suggestedUrlTemplate`	`--url-template`
`templateVariables`	`--var <name>=<value>`
`connectionProperties`	`--prop <name>=<value>`
`driverClass`	`--driver-class`, needed only when the JAR has more than one

`postman dataset source`

Manage the data sources associated with a dataset.

A dataset can contain multiple data sources. You specify the dataset with the -d, --dataset option, and commands that act on a specific source also take its name or ID as an argument.

To use these commands with a cloud dataset, sign in to Postman with the postman login command, or pass the --api-key <key> option to use a specific API key.

`postman dataset source list`

Lists the data sources associated with a dataset.

Usage

postman dataset source list [options]

Options

-d, --dataset <dataset-path-or-id>

Required

Path to a local dataset file or a cloud dataset ID.

--json

Displays results in JSON format.

Examples

postman dataset source list -d ./postman/datasets/customers.dataset.yaml
postman dataset source list -d 14e30f6c-1234-1234-1234-cafef00dc0de

`postman dataset source add`

Adds a data source to a dataset.

Usage

postman dataset source add [options]

Options

-d, --dataset <dataset-path-or-id>

Required

Path to a local dataset file or a cloud dataset ID.

-n, --name <name>

Required

The data source name. This becomes the SQL table name. Not required, and ignored, for a spreadsheet source: see --file.

--source-id <uuid>

Defaults to Random v4 UUID

(Local only) Unique identifier for the data source. If not provided, a random v4 UUID is generated. A cloud dataset assigns its own source ID.

--type <type>

'local' | 'mysql' | 'postgresql' | 'sqlserver' | 'jdbc'

Specifies the source type. If not provided, the type is inferred from --file for a local source or from --driver-jar for a JDBC source.

--file <path>

Path to a local file to add as a source: CSV, JSON, or a spreadsheet (.xlsx, .xls, or .ods). For a cloud dataset, the file is registered as a local file source unless you also pass --upload.

A spreadsheet adds every worksheet in the workbook as its own source, each named source_<worksheet>, and -n, --name is ignored. A single-sheet workbook still produces one source.

--format <format>

Overrides the format the CLI infers for the data source. By default, the format comes from the file extension (.csv, .json, .xlsx, .xls, or .ods) or the source type.

--upload

(Cloud only) Uploads the file from --file to Postman and stores it as a cloud file source. Without --upload, the file stays on your computer and is registered as a local file source instead.

--ref-only

(Local only) References the source file in place without copying it into the dataset resources directory.

--force

(Local only) Overwrites a file of the same name that’s already in the dataset’s resources directory. Use this when you’re replacing a source file you added before. Without it, the copy fails because the file already exists.

The following options configure a database source and apply with --type mysql, --type postgresql, or --type sqlserver.

--host <host>

Required

Database host name.

--port <port>

Database port number. Defaults to 1433 for SQL Server.

--user <user>

Required

Database user name.

--password <password>

Required

Database password.

--database <database>

Required

Database name.

--table <table>

Database table name. Required for SQL Server.

--schema <schema>

Database schema. Applies to PostgreSQL and SQL Server. Defaults to dbo for SQL Server.

The following options apply to SQL Server sources (--type sqlserver) and configure the TLS connection.

--encrypt <true|false>

Defaults to true

Whether to use TLS encryption for the SQL Server connection.

--tls-min-version <version>

'1.2' | '1.3'Defaults to 1.2

The minimum TLS version to use for the SQL Server connection.

--tls-certificate <path>

Path to the CA or server certificate file for the SQL Server connection.

--host-name-in-certificate <hostname>

Overrides the host name expected in the SQL Server certificate.

--trust-server-certificate <true|false>

Defaults to false

Whether to skip verification of the SQL Server certificate. Skipping verification is insecure. Use it only for trusted local testing.

The following options configure a custom JDBC data source and apply with --type jdbc. You supply the driver, and the machine running the command needs Java 8 or newer. To find a driver’s classes, properties, and a suggested URL template before you add the source, use postman dataset jdbc inspect.

--driver-jar <path...>

Required

Path to a JDBC driver JAR file. Repeat the option, or pass several paths after one flag, to add dependency JAR files. Java resolves classes in the order the files are listed.

Postman saves these paths in the dataset. Later commands that query the data source look for the driver at the saved path, so keep the file where it is or update the source with postman dataset source update.

--driver-class <fqcn>

The fully qualified driver class name. Resolved automatically when the JAR contains exactly one driver class.

--driver-name <label>

Defaults to The JAR file name

Label for this driver type in the dataset.

--url-template <template>

Required

The JDBC URL with {{placeholder}} variables, such as jdbc:postgresql://{{host}}:{{port}}/{{database}}.

--var <name=value...>

A value for a {{placeholder}} in the URL template. Repeatable. Use vault:<vault-id>/<secret-id> to reference a Shared Vault secret instead of a literal value.

--prop <name=value...>

A driver connection property. Repeatable, and accepts the same vault: syntax as --var.

--vars-file <path>

Path to a JSON file of --var values, or - to read them from stdin. Each value can be a literal, or a {"$vaultId": "<vault-id>", "$secretId": "<secret-id>"} object to reference a Shared Vault secret. This keeps secrets out of the command line entirely.

--from-source <name>

Reuses the driver JAR, driver class, and URL template from another source in the same dataset.

--java-path <path>

The Java runtime to use. This value stays on your computer and is never written to the dataset. Also read from the POSTMAN_JDBC_JAVA_PATH environment variable.

--no-test

Skips the connection test that runs before the source is written. Resolving the driver class still starts Java, so on a computer without Java, pass --driver-class or --from-source as well.

A literal value passed to --var or --prop is visible in your shell history and in ps output, and it’s stored as plain text in the dataset file (for a local dataset) or sent in the request body (for a cloud dataset). Use a vault: reference or --vars-file for credentials.

To connect to a database through an SSH bastion host (an SSH tunnel), use the following options.

--ssh-host <host>

The SSH bastion host.

--ssh-port <port>

The SSH bastion port.

--ssh-user <user>

The SSH bastion user.

--ssh-private-key <filepath>

Path to the SSH private key. The key contents are read locally when the command runs and aren’t stored in the dataset configuration.

--ssh-host-key <public-key>

The SSH bastion’s public host key.

--ssh-host-key-vault-id <id>

The Shared Vault ID that contains the SSH public host key.

--ssh-host-key-secret-id <id>

The Shared Vault secret ID that contains the SSH public host key.

--ssh-insecure-skip-host-key-verification

Turns off SSH host-key verification. This is insecure. Use it only for trusted local testing.

Passing --user or --password on the command line stores the value as plain text in the dataset file (for a local dataset) or sends it in the request body (for a cloud dataset), and exposes it in your shell history and process list. Because these credentials aren’t protected, use a database account limited to read-only access to only the data this source needs, rather than a privileged account.

Examples

postman dataset source add -d ./postman/datasets/customers.dataset.yaml \
  --name customers \
  --file customers.csv
postman dataset source add -d 14e30f6c-1234-1234-1234-cafef00dc0de \
  --name customers \
  --file customers.csv \
  --upload
postman dataset source add -d ./postman/datasets/customers.dataset.yaml \
  --name production-db \
  --type postgresql \
  --host db.example.com \
  --port 5432 \
  --user readonly_user \
  --password '••••' \
  --database customers
# Add a SQL Server source
postman dataset source add -d ./postman/datasets/customers.dataset.yaml \
  --name orders-db \
  --type sqlserver \
  --host db.example.com \
  --user readonly_user \
  --password '••••' \
  --database orders \
  --table Orders
# Connect to a database through an SSH bastion host
postman dataset source add -d ./postman/datasets/customers.dataset.yaml \
  --name production-db \
  --type postgresql \
  --host db.internal \
  --port 5432 \
  --user readonly_user \
  --password '••••' \
  --database customers \
  --ssh-host bastion.example.com \
  --ssh-user tunnel \
  --ssh-private-key ~/.ssh/id_ed25519

`postman dataset source update`

Updates an existing data source. Only the options you provide are updated.

Usage

postman dataset source update <data-source> [options]

<data-source>

The data source name or unique identifier.

Options

-d, --dataset <dataset-path-or-id>

Required

Path to a local dataset file or a cloud dataset ID.

To update the source configuration, this command supports the same options as postman dataset source add. You can update connection details for a database source, or change the file for a file-based source.

Examples

postman dataset source update production-db \
  -d ./postman/datasets/customers.dataset.yaml \
  --host new-db.example.com
postman dataset source update production-db \
  -d 14e30f6c-1234-1234-1234-cafef00dc0de \
  --port 5433

`postman dataset source remove`

Removes a data source from a dataset.

Usage

postman dataset source remove <data-source> [options]

<data-source>

The data source name or unique identifier.

Options

-d, --dataset <dataset-path-or-id>

Required

Path to a local dataset file or a cloud dataset ID.

Examples

postman dataset source remove customers \
  -d ./postman/datasets/customers.dataset.yaml
postman dataset source remove customers \
  -d 14e30f6c-1234-1234-1234-cafef00dc0de

`postman dataset view`

Dataset view commands enable you to create, manage, and run saved SQL queries. A dataset can contain multiple views. You specify the dataset with the -d, --dataset option, and commands that act on a specific view also take the view’s name or ID as an argument. To learn more, see Example dataset views in Postman.

To use these commands with a cloud dataset, sign in to Postman with the postman login command, or pass the --api-key <key> option to use a specific API key.

`postman dataset view list`

Lists saved views in a dataset.

Usage

postman dataset view list [options]

Options

-d, --dataset <dataset-path-or-id>

Required

Path to a local dataset file or a cloud dataset ID.

--json

Displays results in JSON format.

Examples

postman dataset view list -d ./postman/datasets/customers.dataset.yaml
postman dataset view list -d 14e30f6c-1234-1234-1234-cafef00dc0de

`postman dataset view create`

Saves a view to a dataset.

Usage

postman dataset view create [options]

Options

-d, --dataset <dataset-path-or-id>

Required

Path to a local dataset file or a cloud dataset ID.

-n, --name <name>

Required

The view name.

-q, --query <query>

Required

The SQL query.

--view-id <uuid>

Defaults to Random v4 UUID

(Local only) Unique identifier for the view. If not provided, a random v4 UUID is generated. A cloud dataset assigns its own view ID.

Examples

postman dataset view create -d ./postman/datasets/customers.dataset.yaml \
  -n "active-customers" \
  -q "SELECT * FROM customers WHERE active = true"
postman dataset view create -d 14e30f6c-1234-1234-1234-cafef00dc0de \
  -n "active-customers" \
  -q "SELECT * FROM customers WHERE active = true"

`postman dataset view update`

Updates a saved view. Only the options you provide are updated.

Usage

postman dataset view update <view> [options]

<view>

The view name or unique identifier.

Options

-d, --dataset <dataset-path-or-id>

Required

Path to a local dataset file or a cloud dataset ID.

-n, --name <name>

A new name for the view.

-q, --query <query>

A new SQL query for the view.

Examples

postman dataset view update active-customers \
  -d ./postman/datasets/customers.dataset.yaml \
  --name current-customers
postman dataset view update active-customers \
  -d 14e30f6c-1234-1234-1234-cafef00dc0de \
  --query "SELECT * FROM customers WHERE status='active'"

`postman dataset view delete`

Deletes a saved view from a dataset.

Usage

postman dataset view delete <view> [options]

<view>

The view name or unique identifier.

Options

-d, --dataset <dataset-path-or-id>

Required

Path to a local dataset file or a cloud dataset ID.

Examples

postman dataset view delete active-customers \
  -d ./postman/datasets/customers.dataset.yaml
postman dataset view delete active-customers \
  -d 14e30f6c-1234-1234-1234-cafef00dc0de

`postman dataset view run`

Runs a saved view against a dataset and displays the rows.

Usage

postman dataset view run <view> [options]

<view>

The view name or unique identifier.

Options

-d, --dataset <dataset-path-or-id>

Required

Path to a local dataset file or a cloud dataset ID.

-p, --param <parameter>

Provides a value for a positional placeholder in the view’s query. The first -p value fills $1, the second fills $2, and so on. Repeat the option to pass multiple values, for example -p value1 -p value2.

--json

Displays query results in JSON format.

--debug

Shows detailed debug output for the view run.

Examples

postman dataset view run active-customers \
  -d ./postman/datasets/customers.dataset.yaml
postman dataset view run active-customers \
  -d 14e30f6c-1234-1234-1234-cafef00dc0de

`postman dataset delete`

Deletes a dataset.

To use this command with a cloud dataset, sign in to Postman with the postman login command, or pass the --api-key <key> option to use a specific API key.

Usage

postman dataset delete <dataset-path-or-id> [options]

<dataset-path-or-id>

Path to a local dataset file or a cloud dataset ID.

Options

-y, --yes

Skips the confirmation prompt.

--keep-resources

(Local only) Deletes the dataset file but preserves the associated resources directory, which holds your copied source files. Use this when you want to remove the dataset definition but keep its data, or when another dataset in the same directory shares those files.

Examples

postman dataset delete ./postman/datasets/customers.dataset.yaml
postman dataset delete ./postman/datasets/customers.dataset.yaml \
  -y \
  --keep-resources
postman dataset delete 14e30f6c-1234-1234-1234-cafef00dc0de -y