diff --git a/public/screenshots/variables/prompt-var-dedupe.webp b/public/screenshots/variables/prompt-var-dedupe.webp new file mode 100644 index 00000000..9d0437d6 Binary files /dev/null and b/public/screenshots/variables/prompt-var-dedupe.webp differ diff --git a/public/screenshots/variables/prompt-var-modal.webp b/public/screenshots/variables/prompt-var-modal.webp new file mode 100644 index 00000000..7e3b272a Binary files /dev/null and b/public/screenshots/variables/prompt-var-modal.webp differ diff --git a/public/screenshots/variables/prompt-var-runner.webp b/public/screenshots/variables/prompt-var-runner.webp new file mode 100644 index 00000000..844183e6 Binary files /dev/null and b/public/screenshots/variables/prompt-var-runner.webp differ diff --git a/public/screenshots/variables/prompt-var.webp b/public/screenshots/variables/prompt-var.webp new file mode 100644 index 00000000..e453a696 Binary files /dev/null and b/public/screenshots/variables/prompt-var.webp differ diff --git a/src/pages/variables/_meta.js b/src/pages/variables/_meta.js index a902a1ad..fc7ef8e9 100644 --- a/src/pages/variables/_meta.js +++ b/src/pages/variables/_meta.js @@ -6,6 +6,7 @@ export default { "folder-variables": "Folder Variables", "request-variables": "Request Variables", "runtime-variables": "Runtime Variables", + "prompt-variables": "Prompt Variables", "process-env": "Process Environment Variables", - "interpolation":"Variables Interpolation" + "interpolation":"Variables Interpolation" } \ No newline at end of file diff --git a/src/pages/variables/overview.mdx b/src/pages/variables/overview.mdx index 14734cc8..374bf0aa 100644 --- a/src/pages/variables/overview.mdx +++ b/src/pages/variables/overview.mdx @@ -1,3 +1,5 @@ +import { Callout } from "nextra/components"; + # Variables ### Overview @@ -6,7 +8,7 @@ Variables in the Bruno allow you to store dynamic values that can be reused acro ### Types -There are 6 types of variables you can create: +There are 7 types of variables you can create: - [Global Environments Variables](./global-environment-variables.mdx) - [Environment Variables](./environment-variables.mdx) @@ -14,18 +16,17 @@ There are 6 types of variables you can create: - [Folder Variables](./folder-variables.mdx) - [Request Variables](./request-variables.mdx) - [Runtime Variables](./runtime-variables.mdx) +- [Prompt Variables](./prompt-variables.mdx) Additionally, Process Environment Variables can be defined in an external environment configuration file: - [Process Environment Variables](./process-env.mdx) -Runtime variables get the highest precedence. Process Environment Variables are accessed using the `{{process.env.VAR_NAME}}` syntax and hence don't compete with the above. - ### Variable Precedence and Scope When a variable is accessed, the following precedence is used to determine which value is used: -
+
↑ Higher Precedence
@@ -42,7 +43,9 @@ When a variable is accessed, the following precedence is used to determine which
-Runtime variables get the highest precedence. Process Environment Variables are accessed using the `{{process.env.VAR_NAME}}` syntax and hence don't compete with the above. +- Runtime variables get the highest precedence. +- Prompt Variables are defined using the `{{?:Prompt String}}` syntax and hence don't compete with the above. +- Process Environment Variables are accessed using the `{{process.env.VAR_NAME}}` syntax and hence don't compete with the above. ### Variable Storage @@ -81,6 +84,10 @@ Each variable has its own storage location either within your collection file or Global Local storage + + Prompt + Never stored + Process Environment Separate `.env` file @@ -112,3 +119,7 @@ console.log(bru.getVar('myVar')) // Runtime variables ### Scripting API Please see the [Scripting API](/scripting/javascript-reference#collection-variables) for more information on how to access variables in your scripts. + + + Prompt variables are not accessible via the Scripting API. + diff --git a/src/pages/variables/prompt-variables.mdx b/src/pages/variables/prompt-variables.mdx new file mode 100644 index 00000000..c7cc98eb --- /dev/null +++ b/src/pages/variables/prompt-variables.mdx @@ -0,0 +1,87 @@ +import { Callout } from "nextra/components"; + +# Prompt Variables + +## Overview + +Prompt variables are a special type of **ephemeral variable** in Bruno that allow you to prompt the user for a value at the time a request is executed. Unlike other variable types, prompt variables do not have a predefined value and are not persisted anywhere, they exist only for the duration of a single request execution. Prompt variables are useful for sensitive data, ad-hoc values, or any scenario where you want the user to provide input before sending a request. + +Prompt variables are scoped within a request, meaning they are available only to the request in which they are defined during execution, and their values are not persisted after the request completes. + +### Syntax + +Prompt variables use the following syntax: + +```handlebars +{{?:Prompt Here}} +``` + +- The `?:` indicates that this is a prompt variable. +- The text after the colon (`:`) is the prompt message shown to the user. + +Prompt variables are highlighted in blue in the Bruno UI. + +![prompt-var](/screenshots/variables/prompt-var.webp) + +### Prompt Variable Modal + +When prompt variables are detected, Bruno displays a modal dialog listing all prompt variables and their prompt messages. You may provide values for each before the request is sent. If you cancel the modal, the request will not be sent. + +### Using Prompt Variables + +You can use prompt variables anywhere markup variables are supported in Bruno, such as in URLs, headers, query parameters, and request bodies. + +When you execute a request containing one or more prompt variables, Bruno will display a modal dialog prompting you to enter a value for each unique prompt variable. If the same prompt variable appears multiple times in a request, you will only be prompted for it's value once, and all instances will be replaced with the value you provide. + +![prompt-var-modal](/screenshots/variables/prompt-var-modal.webp) + + + If you leave a prompt variable blank, it will be replaced with an empty string in the request. + + +### Deduplication + +If you use the same prompt variable multiple times in a request, Bruno will only prompt once and substitute the value everywhere. + +#### Example: + +For the following request referencing the `Username` prompt variable twice: + +```json +{ + "user": "{{?:Username}}", + "profile": { + "name": "{{?:Username}}" + } +} +``` + +You will only be prompted for "Username" once: + +![prompt-var-dedupe](/screenshots/variables/prompt-var-dedupe.webp) + +### Behavior in Bruno CLI + +If you run a collection containing prompt variables using Bruno CLI, any requests containing prompt variables will be **skipped** and marked as `skipped` in the CLI output. This is because CLI does not support interactive prompting. + +### Behavior in Runners + +If you run a collection containing prompt variables using the Bruno Runner, any requests containing prompt variables will be **skipped** and marked as `skipped` in the run results. This is because the Runner does not support interactive prompting. + +![prompt-var-runner](/screenshots/variables/prompt-var-runner.webp) + +### Viewing Prompt Variables + +Prompt variables are ephemeral and only exist during request execution. They are not shown in any variables viewer and are not persisted. + + + Prompt variables are only available during the execution of a request and are not persisted or accessible after the request completes. + + +## Notes + +- Prompt variables are ideal for sensitive or temporary values you do not want to save or share. +- If you do not provide a value, the prompt variable will be replaced with an empty string. +- Prompt variables are highlighted in blue in the Bruno UI. +- Prompt variables are not available in scripts (pre-request or post-response). +- Bruno CLI and Bruno Runner both skip requests containing prompt variables.