**Source URL:** https://limited.veevavault.dev/qualityone/vault-dx/plugins/reference/vault

# vault

Connect to a Vault instance, understand its application family and environment, retrieve data with VQL, and stay signed in across tool calls.

## Overview

For any Vault user working in Claude Code. Use the `vault` plugin to authenticate Claude to a Vault, identify the application family and API version in use, and ensure Claude answers specifically for the Vault in work rather than generically.

### Dependencies

| Plugin / Tool | Why |
| --- | --- |
| Vault CLI (`vault`) | Sign-in, the credential store, and queries route through the CLI when installed. Otherwise the documented Vault API is used. |
| Vault Documentation MCP | Answers Help, API, VQL, and SDK questions from official references. |

### Out of scope

| Topic | Owned by |
| --- | --- |
| Configuration authoring (MDL, lifecycles, workflows, picklists, and all other Vault Component Types) | [`vault-administrator`](/qualityone/vault-dx/plugins/reference/vault-administrator/) |
| Bulk data loads and extracts | [`api`](/vault-dx/plugins/reference/vault-developer/#api-skill) |
| Environment and sandbox management | Vault Admin UI |
| VPK packaging and deployment | Vault Admin UI (outbound and inbound packages) |
| Security profiles, permission sets, user and group management | Vault Admin UI |
| Vault Java SDK entry-point classes and Custom Pages | [`vault-developer`](/qualityone/vault-dx/plugins/reference/vault-developer/) |

## Skills

| Skill | Invoke with | What it does |
| --- | --- | --- |
|  | `/vault:login` | Sign in, classify production vs. sandbox, and profile the Vault's application family and API version. |
|  | `/vault:query` | Write, review, and run VQL queries against a Vault. |

The  rules apply to every skill in `vault`, `vault-administrator`, and `vault-developer`.

---

### login Skill

Sign in to a named Vault, classify the target as production or sandbox, and profile the Vault's application family and API version so that all skills answer for the Vault in work.

For Vault admins, developers, and every other skill that needs a live Vault session. Use this skill to sign in, stay signed in across tool calls, switch Vaults by DNS, classify the target as production or sandbox before any write, and profile the Vault's application family and API version. The `login` skill gives every other skill the context it needs to answer accurately for your specific Vault.

#### Key Concepts: Application Families

| Family | Key Characteristics |
| --- | --- |
| Clinical (CTMS, eTMF, Study Startup) | Trial management, investigator sites, regulatory submissions |
| Commercial (PromoMats) | Content approval, distribution |
| CRM | Commercial field force operations, account management, call recording |
| Medical (MedComms, MedInquiry) | Medical information, inquiry management |
| Quality (QualityDocs, QMS, Training) | Document control, audits, CAPAs, training |
| Regulatory (RIM, Submissions) | Registration, dossier management, agency submissions |
| Safety (Safety) | Adverse event reporting, case processing |
| Platform | No domain-specific objects or functionality |

#### Key Concepts: Environment Type

| Type | Implication |
| --- | --- |
| Production | Changes are live. Use caution on writes and with sensitive data. |
| Sandbox | Generally safe for experimentation and testing. |

<Aside type="note">
Some APIs, VQL syntax extensions, and SDK entry points are version-gated. The version is available from the `/api` endpoint response. For the API release schedule, see About Vault Releases ([https://rn.veevavault.help/en/gr/about-vault-releases/](https://rn.veevavault.help/en/gr/about-vault-releases/)) in Vault Help.
</Aside>

#### Triggers

*   Explicit: "Sign in to my Vault", "Log in to the QA sandbox", "Switch to prod", "Am I still signed in", "Is this Vault a sandbox", "What kind of Vault is this", "Is this a Quality Vault", "What API version does this Vault support", "Which plugins do I need for this Vault".
*   Implicit: Another skill needs a live session, a production/sandbox classification, or the Vault's profile before it acts. The user says "I'm using a Clinical Vault" or asks what features their Vault has. A call fails with a login, token, or credentials error. The user names a Vault and wants work run against it.
*   Negative: Do not write the query, the MDL, or the REST call. Do not drive a browser or OAuth flow directly. Do not manage users and security policies.

#### Success criteria

*   On first contact with a Vault in a session, establish its profile: `domain_type__v`, `vault_family__v` and `vault_application__v` with `include_application=true`, and the last general version from `GET /api/` with a newer version named as present when the list shows one. State the profile once on the same line as the classification (for example "DEV (mycompany-dev.veevavault.com), Sandbox, Platform, API v26.2") and never re-ask for the rest of the session.
*   The application family and applications never change for a Vault and may be cached per DNS across sessions. The environment type must be read live before every write. The API version is re-read when a call is rejected for its version.
*   Before handing over a sign-in command, ask how the user signs in to that Vault (SSO, a Vault password, or a token they hold).
*   For a password or token, the hand-off must be the `vault login` line with `--password` (and `--username`) or `--access-token` and no value, so the CLI prompts for the secret with hidden input. The skill never runs it.
*   `login token` is gone, and the skill must not mint an API access token itself. A token generated through `vault api` comes back in the response and lands in the transcript. After a password or SSO sign-in the skill should offer an API access token, because a stored session idles out mid-task and the CLI holds no password to renew it. The user creates it in the API Access Tokens section of their Vault user profile and signs in with `vault login --dns <dns> --access-token` in their own terminal.
*   The classification (`PRODUCTION`, `SANDBOX`, `DEMO`, `TEST`, `UNKNOWN`) is read from `domain_type__v` before any write and stated with the target DNS in one line. A DNS name is never treated as evidence of environment type.
*   Against `PRODUCTION` or `UNKNOWN` the skill must not execute the write. It reports the DNS, the classification, and the exact command for the user to run. `UNKNOWN` means missing rights or a failed check, and counts as production.
*   The skill must never ask for a secret (password, access token, session ID, OAuth token) in chat, and must never run the store command on the user's behalf. A secret the user pastes into chat is treated as compromised: Declined, with rotation advised.
*   A failed login is never retried in a loop. The auth burst limit, counted per username and Vault DNS in a one-minute window, is named as the reason.
*   Endpoint paths and field API names must come from the Vault Documentation MCP and must not be inferred.
*   When the ask is a query, a load, an MDL execute, or a REST call, the skill signs in, names the skill that owns the work, and stops.
*   Answers, queries, and suggested features must fit the profiled family and release. A feature gated to a release later than the Vault's top API version is named as not yet available.
*   The CLI has no command that lists stored Vaults or credentials. The skill must have the full DNS before it acts. When the user gives a label or nickname instead, it asks for the DNS rather than guessing one.

#### Out of scope

| Topic | Owned by |
| --- | --- |
| VQL query syntax and execution |  |
| MDL authoring and execution | [`vault-administrator`](/vault-dx/plugins/reference/vault-administrator/#mdl-skill) |
| Reading a Vault's configuration from a workspace | [`vault-administrator`](/qualityone/vault-dx/plugins/reference/vault-administrator/) |
| Endpoint paths, request shapes, response fields | Vault Documentation MCP |
| Managing users and security policies | Vault Admin UI |
| Creating an API access token without the CLI | Vault Admin UI |
| Record or document data loads | [`api`](/vault-dx/plugins/reference/vault-developer/#api-skill) submits the load file as a Loader job |
| Which components a Vault has, and what depends on what | [`config`](/vault-dx/plugins/reference/vault-administrator/#config-skill) |

---

### query Skill

Write, review, and run VQL queries against a connected Vault.

For any Vault user who needs to retrieve data from a Vault. Use this skill to filter records, traverse object relationships, paginate through large result sets, and target the correct object type using valid VQL syntax and real field API names.

#### Triggers

*   Explicit: "Write me a query", "Help me with VQL", "Use the query skill", `/vault:query`. User pastes a VQL statement and asks for review or improvement.
*   Implicit: User describes a data retrieval need in natural language. For example, "get all records where…", "find all documents owned by…", "pull all X from Y". User asks why a query is slow or returning wrong results. User needs to traverse object relationships or paginate through large result sets.
*   Negative: Do not trigger for Vault Java SDK source code generation. Hand off to [`java-sdk`](/vault-dx/plugins/reference/vault-developer/#java-sdk-skill). Do not trigger for MDL schema changes. Hand off to [`mdl`](/vault-dx/plugins/reference/vault-administrator/#mdl-skill). Do not trigger for building, explaining, or cloning Vault Reports and dashboards. Hand off to [`reporting`](/vault-dx/plugins/reference/vault-administrator/#reporting-skill). Running a report stays in the Vault UI. Do not trigger when the goal is a bulk data extract. Hand off to [`api`](/vault-dx/plugins/reference/vault-developer/#api-skill).

#### Success criteria

*   Generated queries must use correct VQL clause order: `SELECT`, `FROM`, then optionally `FIND`, `WHERE`, `ORDER BY`, `MAXROWS`/`PAGESIZE`/`PAGEOFFSET`.
*   Generated queries must never use `SELECT *`. `SELECT` must list specific fields.
*   All field and object names must use API names (`__v` or `__sys` suffix). Display names are only valid inside a `TOLABEL()` wrapper and must not appear bare in field positions or `WHERE` clauses.
*   The documents object must be referenced as `documents`, not `documents__v`.
*   Relationship subqueries must use the `__vr` relationship token, not the related object's API name.
*   Null checks must use `= null` and `!= null`. `IS NULL` and `IS NOT NULL` are not valid VQL and must never appear in generated queries.
*   Picklist values must be confirmed with the user before generating. Guessed picklist values are not acceptable.
*   All assumptions and ambiguities must be surfaced and confirmed before the query is generated. Silent assumptions are not acceptable.
*   Generated and reviewed queries must be directly usable. Correct API names, valid syntax, no placeholder field names.
*   When answering a general VQL question, the response must use placeholder names (for example `<object__v>`, `<field__v>`) in any sample query. A runnable query with real API names must not be presented as if correct.
*   Every response that includes a generated or reviewed query must include a next step offer to run the query against the user's Vault.
*   The skill must reuse the session established by . It must never prompt for credentials or initiate a sign-in on its own.
*   The skill must not execute a query against Vault until the user explicitly confirms via the next step offer.
*   Undocumented API endpoints must never be guessed. Endpoint questions must be answered using the Vault Documentation MCP or handed off to [`api`](/vault-dx/plugins/reference/vault-developer/#api-skill).

<Aside type="note">
For VQL syntax and clause reference, see the [VQL reference](https://general.veevavault.dev/vql/).
</Aside>

#### Out of scope

| Topic | Owned by |
| --- | --- |
| Vault Java SDK source code that uses or wraps a query | [`java-sdk`](/vault-dx/plugins/reference/vault-developer/#java-sdk-skill) |
| Vault API calls unrelated to query execution | [`api`](/vault-dx/plugins/reference/vault-developer/#api-skill) |
| Object and field schema changes | [`mdl`](/vault-dx/plugins/reference/vault-administrator/#mdl-skill) |
| Record data loading or bulk extracts | [`api`](/vault-dx/plugins/reference/vault-developer/#api-skill) |
| Vault credential management and sign-in |  |

---

### Vault CLI

These rules apply to every skill in `vault`, `vault-administrator`, and `vault-developer`. A skill's own criteria add to them and never override them.

#### CLI routing rules

*   The skill must check for the CLI once per task (`vault version`) before it picks a path, and compare the result with the minimum version, 26.2.4, which the plugin README names.
*   When the CLI is installed and has a command for the operation, the run step must be that command. The skill must not hand back curl or a script for something the CLI does.
*   With the CLI installed, a skill must not write its own client or sign-in code for Vault. The documented API is the path only when the CLI is absent.
*   A missing or outdated CLI must never block the task. The skill must offer to fix it first: run the README's install command on the user's yes. For an installed CLI older than 26.2.4, show the newer release with `vault upgrade --check`, then hand `vault upgrade` to the user or run the install command on their yes.
*   After a declined install, the skill must take the request shape from the Vault Documentation MCP, call the API directly, and carry on without raising the install again.
*   The plugins must not bundle helper scripts that stand in for the CLI, such as a login helper or a configuration puller. The two paths are the CLI and the documented API. There is nothing in between.
*   The production check owned by `vault`'s `login` skill must run before any write, on both paths. Reads skip it. The CLI does not classify the target, so a CLI command is never evidence that a write is safe.
*   `-y`/`--yes` must never appear in a command the skill runs or suggests. It skips the CLI's confirmation prompt and its safety checks. One exception: when `vault config pull` stops before removing files the Vault does not have, and the workspace was committed just before, the skill may rerun that same pull with `-y`/`--yes`, restore the files from git, and say so in its report. It is never a first move, never on a push, and never a way to pull a different Vault into a workspace.
*   After every write the skill must read back what changed. CLI output is not evidence. `vault mdl` prints "MDL executed." and nothing else.
*   A secret must never be placed on a command line the skill runs (`--password`, `--access-token`, `--session-id`). The user runs sign-in themselves.
*   A skill must never ask the user to write a password, session ID, or token into a project file (a settings JSON, a properties file, a build descriptor), and must not choose a path that needs one. The CLI's credential store and the signed-in session are the only places a credential lives. A build-tool plugin that reads its own credential file is not a route to a Vault.
*   When a skill needs an endpoint the CLI has no dedicated command for, it must call it through `vault api` with the stored session, and must not read the session out of the CLI's credential store to build its own request.
*   A skill must start from the plugins' shared CLI reference for commands and flags, so a task does not begin by rediscovering the CLI. When a command fails, or the reference and the installed CLI disagree, the skill must check `--help` and follow the installed CLI. It must not search the CLI's install folder or the user's home directory to work out how the CLI behaves.
*   A change made through a workspace must follow the order: pull, author, `vault config push --dry-run`, `vault config push`, read back. The pull comes first on every change, not once per session. `push --dry-run` is not the freshness check. It compares with the Vault as it is now, so a change made on the Vault since the last pull shows up as an update the push would undo.
*   The workspace must be a git repository from its first pull, and the skill must commit before every pull, so a pull can never take authored work with it.
*   When a push ends with errors or lands only partway, the skill must stop, commit, read back what landed, and report what landed and what failed before any further pull or push.
*   The skill must read the workspace as the CLI writes it: each subcomponent is its own file under its parent's folder, XML-bodied attributes sit in sidecar files beside the component file, and a list attribute keeps the form the pull wrote. A subcomponent absent from the parent's file is not missing from the Vault.
*   A CLI limitation must be stated as a limit of the CLI the user has installed, never as a permanent fact.
*   When a CLI command is what keeps failing, the skill must leave the CLI path for the API path rather than repeat the command. "Run it again" is offered at most once.
*   A workspace written by `vault config pull` belongs to the CLI. The skill must not hand-edit files in it to repair what the CLI wrote, and must not pull while new files are uncommitted, since a pull removes new files the Vault does not have. The skill has the user commit or copy them first, then pulls. New components are authored as files in the workspace, the same as changes to existing ones.
*   Presence is not correctness: after a write the read-back must compare content, not just confirm the component exists. Vault creates a placeholder lifecycle of the right name when an object that names a missing lifecycle is created.
*   With two Vaults in one task (a source and a target), the skill must state both by DNS with the target's classification before the first command, put an explicit `--dns` on every command after that, and send writes only to the Vault the user named as the target.
*   A command handed to the user must work in the user's shell. The skill asks which shell before the first hand-off. Windows PowerShell has no `&&` and does not expand `~` for a program's arguments. Git Bash rewrites an argument that starts with `/` into a Windows path unless `MSYS_NO_PATHCONV=1` is set. `zip` is not assumed to exist on Windows.

#### Command surface

What the skills may rely on, on the CLI version the plugin README names. A command not in this table is treated as missing, and the skill takes the API path.

| Operation | Command | Used by |
| --- | --- | --- |
| Sign in | `vault login` | `login` |
| Run a VQL query | `vault query "<vql>" --format table|json|csv`, `--all` for every page | `query` |
| Execute one MDL statement | `vault mdl "<statement>"` | `mdl` |
| Pull, preview, and deploy configuration, with Java under `javasdk/` and Custom Page distributions under `custom_pages/` | `pull` (`--dry-run`), `push` (`--dry-run` for preview. A push that would delete components lists them and stops for confirmation.) | `config`, `mdl`, `java-sdk`, `custom-pages`, `ai-agents` |
| Call any Vault endpoint with the stored session | `vault api <path>` | Every skill that needs an endpoint with no dedicated command |

No dedicated command, so these go through `vault api` with the CLI installed and the documented API without it: Vault File Staging, data loads (submitted as Vault Loader jobs by the `api` skill), job status, listing and revoking API access tokens, and any endpoint outside the rows above. The `login token` command is gone. Token endpoints are called through `vault api`, and no skill generates a token.

The CLI has no command that lists stored Vaults or credentials. A Vault is always named by its full DNS, put on an explicit `--dns` on each command. The skill never resolves a label or nickname against a stored list, since there is none.

#### Known CLI limits

Known limits on the CLI version the plugin README names. These are interim: each row is retired when the CLI changes, none of them is a skill requirement. A skill states them as limits of the installed CLI.

| Limit | What the skill does |
| --- | --- |
| `config push` does not order new components that depend on each other | Push leaves first, dependants after. Never promise that a push orders anything. |
| `config push` sends a Custom Page distribution to an endpoint that does not accept the upload | Upload the distribution through `vault api` with the documented distribution upload call, then pull. |
| `config push` can fail on a class under `javasdk/` while the components in the same push deploy | Upload the class through `vault api` on the documented single-source-file call. |
| A push or pull that lists errors or skipped components still ends with "complete" | Read the errors and skipped blocks, never the last line or a 0 exit code. |
| `config pull` writes a multi-value list attribute with doubled quotes, `('A'', ''B')` | Leave the file as the pull wrote it. A value reused in a `vault mdl` statement is written in standard form `('A', 'B')`. A push that fails on a component whose change is such a list is sent as a `vault mdl` statement instead. |
| `config pull` writes over modified local files without asking, and stops only before removing local files the Vault does not have | Commit before any pull. State the drop count before pulling over an existing workspace. |
| No compare command, and `config pull` has no type filter | Freshness is `config pull --dry-run` against the workspace's own source Vault, which prints counts of what a pull would change and writes nothing. A pull always takes the whole Vault. |
| `vault query` output has no record total | Read the total through `vault api` on the query endpoint, from `responseDetails.total`. |
| `--password` and `--access-token` take no value. The CLI prompts for the secret with hidden input. | Hand over the plain `vault login` line for the user to run. |

#### Out of scope

| Topic | Owned by |
| --- | --- |
| Installing and updating the CLI | The plugin README and the `login` onboarding |
| Whether a target is production | `vault`'s `login` skill |
| What each command does inside a skill | That skill's own section |