Skip to main content
Warp Vault provides a simple Query Language (VaultQL) that allows you to search for and extract specific credential provider configurations stored in your vault. This feature helps you extract any properties you might need in scripts or other parts of your workflow. Using the Warp CLI command gh warp vault query, you can supply a query to locate one or more credentials and optionally retrieve only a specific property or nested value.

​
Quick Example

The following example demonstrates how VaultQL can be used in a shell scripting scenario. Credentials are queried from Warp Vault and passed into GitHub Enterprise Importer.

​
Query Syntax

A query is specified at the beginning of the command and must be enclosed in parentheses. An optional extraction path (to pull out a specific property) is appended immediately after the closing parenthesis.

​
General Format

  • Query Elements: A comma-separated list of key/value pairs used to match provider properties.
  • Extraction Path: A dot-prefixed path indicating which property to return from the matched provider.
Both query elements and extraction paths are case-insensitive.

​
Query Elements

Each element in the query helps narrow down your search. There are two types of elements:

​
Top-Level Properties

These match properties at the root level of a provider’s JSON. Supported Keys The type and uuid keys are always available. Syntax Example: Searches for a provider with the specified UUID: (uuid:C3AA88A0-0B1A-4567-B45F-6DB024F15FDE) Searches for providers of type GitHubDestination: (type:GitHubDestination)

​
Data Path Elements

These match properties within the provider’s “data” field. When using these in a query, begin the element with a period (.). Syntax Example Matches a provider whose data contains the key organization_slug with the value your-github-org-slug: (.organization_slug:"your-github-org-slug")

​
Optional Elements

You can use the ? prefix to mark a query element as optional. This helps refine the search when some properties might not be available on every provider. Syntax Example The following query indicates that while it’s preferable for the returned provider to have an organization_slug of org3, it isn’t mandatory for the match: (?.organization_slug:"org3") Multiple elements are separated by commas. All non-optional elements must match for a provider to be considered, while optional elements contribute to a “best match” ranking if several providers qualify.

​
Extraction Paths

After the closing parenthesis of your query, you can specify an extraction path to return just one property instead of the entire provider JSON. Syntax Example Returns the value of organization_slug from the matching provider:
Syntax Example - Nested Properties Retrieves the nested password field inside the credentials object of a Bitbucket Server provider:

​
Examples

Full Provider Retrieval Returns the complete JSON object for the provider with the specified UUID:
Specific Property Extraction Returns only the organization slug from the matched provider:
Nested Property Extraction Returns the nested password value (e.g., “bbs-password”) from within the provider’s credentials:
Using Optional Elements for Flexible Matching
Query Mandatory
  • type:DemoProvider
    • Only providers of type DemoProvider are considered.
Optional
  • ?.organization_slug:"org3"
    • Prefers a provider with an organization slug of org3.
  • ?.access_scope:"global"
    • Alternatively, a provider with global access_scope is acceptable.
Extraction
  • .pat
    • Returns only the personal access token from the matched provider.
Return Value The pat value of the provider that best matches the criteria. Strict Queries The following strict query requires a DemoProvider with an exact organization_slug of org3. If no provider meets all criteria, nothing is returned (and an error is reported).
Matching Behavior & Tips Mandatory vs. Optional Providers must match all mandatory (non-optional) elements. Optional elements help select the best match when multiple providers qualify. Case Sensitivity Query keys and values are normalized (case-insensitive), so you can use uppercase or lowercase letters interchangeably. No Matches If no provider meets the mandatory criteria, the command will return an error indicating that no provider matches the query. Extraction Fallback If you omit an extraction path, the command returns the complete JSON of the best-matching provider.