# CLI command reference

Every dv command a workspace can use, grouped by job, with what each does, its main options, who can run it and whether it changes anything.

This page lists the commands of the Data Visions command line, `dv`. To install it and sign in, see [Install and sign in to the CLI](article:9b9b3a9f-142d-4159-aae3-a9414adb33fc). For the module workflow these commands fit into, see [Build a module with a coding agent, start to finish](article:6e6343d4-3801-4e7d-a21a-9722fb4ee89b).

## How to read this page

- **Who** is who can run it. *Everyone* means anyone signed in, limited by their role. *Admin* means a Workspace Admin. A command you aren't allowed to use is refused by Data Visions with the reason.
- **Changes** marks commands that change something in your workspace (or, for websites, on the public internet). Everything else only reads.
- **Local** commands work on files on your computer and don't need you to be signed in.
- Everything else acts in the workspace shown by `dv dev status`. Check it before any command that changes things.
- `<CODE>` is a module code such as `TOOL_CALIBRATION`. `[folder]` in square brackets is optional.
- Every command has `--help` for its full list of options. Many list commands take `--json` for machine-readable output.

## General

| Command | What it does | Who |
|---|---|---|
| `dv version` | Shows the CLI's version (`data-visions-module-sdk X.Y.Z`). | Local |
| `dv guide` | Prints the whole module workflow, step by step, with the SDK guide to read for each step. Written for coding agents starting cold. | Local |
| `dv capabilities` | One summary of everything the platform offers module developers. `--json` for the full data. | Admin |

## Session: `dv dev`

| Command | What it does | Main options |
|---|---|---|
| `dv dev connect` | Signs in and saves the session. | `--url <your-address>` (always give it), `--tenant <slug>`, `--email`, `--password-stdin` |
| `dv dev status` | Shows the address, who you are, the workspace and when the session expires. | |
| `dv dev tenant <slug>` | Switches the session to another workspace you belong to. | |
| `dv dev token` | Prints the session's sign-in token, for your own scripts. Treat it like a password. | |
| `dv dev logout` | Deletes the saved session from this computer. | |

## Modules: look around

| Command | What it does | Who |
|---|---|---|
| `dv modules list` | The modules your workspace can see, and which are yours. Marketplace modules in the list are only running for you if they show as subscribed. | Everyone |
| `dv modules status <CODE>` | One module's details. | Admin |
| `dv modules versions <CODE>` | The module's stored versions. | Everyone |
| `dv modules connections` | Which modules use which: services, standard interfaces, outside APIs, and any contract mismatches. `--module <CODE>` for one module. | Admin |
| `dv modules interfaces` | The standard interfaces a module can implement or depend on. | Local |
| `dv modules shares <CODE>` | Your module's owner and the other workspaces it is shared with. Read only. | Admin |
| `dv modules diff <CODE>` | How your installed copy differs from the original, for a module you changed after installing it. | Everyone |
| `dv modules checkouts [CODE]` | Who in your workspace has a module checked out and hasn't checked it in. | Admin |
| `dv modules data-migrations <CODE>` | Your workspace's data migration steps for a module: applied, failed (with the error), waiting or pending. | Admin |
| `dv modules preview <CODE>` | Opens the module's screens in your browser, signed in as you. `--print-url` prints the address instead. | Admin |
| `dv modules publish-status` | Your workspace's Marketplace submissions and their review state. | Everyone |
| `dv modules purchases` | Module copies your workspace has bought. | Admin |

## Modules: check before you deploy

| Command | What it does | Main options | Who |
|---|---|---|---|
| `dv modules validate <folder>` | Runs the same checks the platform runs on upload, on your own copy. Each finding shows where, what, why and the fix. Exits with an error when there are errors. | `--json`, `--include-info`, `--marketplace` (also fail on anything that would block a listing) | Local |
| `dv modules scan <folder>` | Security scan, with the same scanners and severities as the platform. *Critical* findings block a deploy; *high* findings block a Marketplace listing. | `--json` | Local |
| `dv modules rules` | The review rules (R1 to R11) every module is built and reviewed against. | `--json` | Local |
| `dv modules review <folder>` | Runs the full module check without deploying: validation, security scan, vulnerable libraries and the AI code review. Takes a minute or more. A deploy of the same files reuses the result. | `--json` | Admin |
| `dv modules escalate <sha256>` | Appeals a build the module check blocked to Data Visions staff, who approve that exact build or reject it with notes. For findings that are wrong, not for skipping real fixes. | `--reason "..."` | Admin |

See [Publish a module: the module check](article:cfb41dcb-edee-4f32-979c-d0f041eff1f8).

## Modules: deploy and update

All of these **change** your workspace and need a Workspace Admin.

| Command | What it does | Main options |
|---|---|---|
| `dv modules deploy <folder>` | Checks the module on your computer, uploads it, runs the module check, registers the new version as owned by your workspace and restarts your workspace's modules with it. Existing subscribers get the new version. | `--subscribe <your-workspace-slug>` on the **first** deploy, so the module appears for your people. `--no-promote` stops after the upload and the server's checks. |
| `dv modules promote <CODE>` | Registers your latest checked upload. `deploy` does this for you. | `--version` |
| `dv modules update <CODE> [CODE...]` | Moves your installed copy to the newest listed version and restarts your modules. Name two modules to update them together when their libraries depend on each other. | `--discard-fork` throws away your own changes to a Marketplace module (can't be undone) |
| `dv modules data-migrations <CODE> --retry` | Runs the pending data migration steps now, starting at a failed one, after you fixed what made it fail. | |

The version in `module.json` must go up with every deploy: a version that's already stored with different files is refused. Without `--subscribe`, a first deploy registers the module but nobody sees it in the sidebar. You can only subscribe your own workspace. See [Versions, drafts and history](article:b7f15cbd-b00f-42e3-a457-7a5b68642aeb).

## Modules: check out and check in

For modules your workspace owns. A check-in never goes live by itself: it becomes the next revision of the module's draft, which an admin previews and publishes in the Module Builder.

| Command | What it does | Changes | Who |
|---|---|---|---|
| `dv modules checkout <CODE> [folder]` | Copies the module's latest code (live, or the open Module Builder draft) into a new folder. With Git installed, the folder is a Git repository: you work on `main`; the branch `platform` holds the platform's copy. | No | Admin |
| `dv modules pull [folder]` | Merges the platform's latest into your check-out. Commit your own work first; Git marks any conflict. | No (your folder only) | Admin |
| `dv modules checkin [folder]` | Sends your changes as the draft's next revision, and reports any errors the check found. Refused if someone checked in since your check-out: pull, resolve, commit, check in again. | Yes (the draft) | Admin |

Main option for `checkin`: `-m "what you changed"`. See [Several people changing one module](article:b6d833a3-f770-4064-81f5-1152f4bd529f).

## Modules: Marketplace

| Command | What it does | Changes | Who |
|---|---|---|---|
| `dv modules publish <CODE>` | Submits your module's latest version for Marketplace review. On approval it's listed for other workspaces. The manifest must allow a Marketplace listing. `-m "release notes"` for the catalog. | Yes | Admin |
| `dv modules buy <CODE>` | Without `--confirm`, shows the price and what you get and give up by buying your own copy of a Marketplace module. With `--confirm <CODE>`, buys it: you're charged, you change it in the Module Builder from then on, and it no longer gets Marketplace updates. Can't be undone. | Yes (and costs money) | Admin |

## Module actions: `dv actions`

Everything a module's screens can do is an **action**: one of the module's own routes, with the same permission and rules as in the app. Only the actions your role allows are listed.

| Command | What it does | Main options | Who |
|---|---|---|---|
| `dv actions list <CODE>` | The module's actions you can run. | `-q "words"` to search, `--json` | Everyone |
| `dv actions show <CODE> <ACTION>` | One action: what it does, the permission it needs and its arguments. | | Everyone |
| `dv actions run <CODE> <ACTION>` | Runs the action as you. Actions that change data change real records. | `--args '{...}'` (path and query values by name, the request body as `"body"`), `--args-file args.json` | Everyone (changes data when the action does) |

Some actions need a person's approval in the app and can't be run here.

## Reports: `dv reports`

| Command | What it does | Main options | Changes | Who |
|---|---|---|---|---|
| `dv reports list` | Reports you can see. | `--module <CODE>`, `--json` | No | Everyone |
| `dv reports module <CODE>` | A module's Reports tab as you see it: ready-made reports, saved reports and the permissions a report can be limited to. | `--json` | No | Everyone |
| `dv reports templates` | Ready-made reports from your modules, with the values and permission each needs. | `--module <CODE>` | No | Everyone |
| `dv reports show <ID>` | One report with its full spec, to edit and send back with `update`. | | No | Everyone |
| `dv reports preview` | Renders a spec with your data without saving it, as an HTML page. | `--spec-file`, `--out`, `--open`, `--filter field=value` (repeatable) | No | Everyone |
| `dv reports render <ID>` | A saved report as an HTML page, with its data fetched now as you. Print it to PDF from the browser. | `--out`, `--open`, `--filter` | No | Everyone |
| `dv reports create` | Saves a new report. | `--name`, `--spec-file`, `--description`, `--shared`, `--module`, `--permission` | Yes | Everyone |
| `dv reports from-template <TEMPLATE>` | Saves a new report from a module's template. | `-p name=value` (once per value), `--name` | Yes | Everyone |
| `dv reports update <ID>` | Renames it, replaces its spec, or sets its module and permission. | `--name`, `--description`, `--spec-file`, `--module`, `--permission` | Yes | The report's owner or an admin |
| `dv reports share <ID>` | Shares a report to view, with named people or everyone. Replaces the list. | `--user-id` (repeatable), `--everyone` | Yes | The owner, with permission to share reports, or an admin |
| `dv reports delete <ID>` | Deletes a report for good. Asks first. | `--yes` skips the question | Yes | The owner or an admin |

## Agents, tools and services

| Command | What it does | Who |
|---|---|---|
| `dv agents list` | Your workspace's agents. | Admin |
| `dv agents chat <AGENT_CODE> "message"` | Sends one message to an agent and prints its reply and the tools it called. The agent runs in your workspace with your permissions, so it can change records. `--json` for the raw reply. | Everyone (as far as the agent's tools allow) |
| `dv tools list` | The modules' assistant tools, with the permission each needs and whether it waits for an approval. `--module <CODE>`. | Admin |
| `dv services list` | The services modules offer each other. | Admin |
| `dv data-connectors list` | The data connectors a module can use. | Admin |

See [Agent tools, skills and scripts](article:f1c6d74e-dd1b-4ef1-a375-968d115a6364).

## Logs: `dv sandbox logs`

| Command | What it does | Who |
|---|---|---|
| `dv sandbox logs` | The recent log of the place your workspace's modules run: errors, slow requests, start-up problems. `-n 200` for the last 200 lines (default 100). | Admin |

Run it when a module doesn't start after a deploy.

## Workspace theme: `dv tenants theme`

Your workspace's brand colors and fonts. Every module's screens follow them.

| Command | What it does | Changes | Who |
|---|---|---|---|
| `dv tenants theme show` | The current theme and the screen variables made from it. `--json` for the full data. | No | Everyone |
| `dv tenants theme tokens` | Every setting a theme may have, what it does, and the approved fonts. | No | Everyone |
| `dv tenants theme validate <file>` | Checks a theme file without saving it. | No | Admin |
| `dv tenants theme set <file>` | Replaces the theme. Refused, with fixes, if a check fails. | Yes | Admin |
| `dv tenants theme history` | The last 20 theme changes. | No | Admin |
| `dv tenants theme rollback` | Restores the theme from before the latest change. Asks first (`--yes` skips). | Yes | Admin |
| `dv tenants theme reset` | Goes back to the default look. Asks first (`--yes` skips). | Yes | Admin |

## Websites: `dv sites`

Your workspace's public websites. *View*, *Manage* and *Publish* below are the **View websites**, **Manage websites** and **Publish websites** permissions. Commands marked **Live** change what the public sees.

| Command | What it does | Main options | Needs |
|---|---|---|---|
| `dv sites list` | Your websites. | `--json` | View |
| `dv sites show <SITE>` | One website: its versions, domains and the DNS records each domain needs. | `--json` | View |
| `dv sites templates` | Websites the platform can make from its own templates. | | View |
| `dv sites feeds-available` | The module feeds you can give a website. | | Manage |
| `dv sites create <SLUG>` | Creates a website. | `--name`, `--feed <FEED>` (repeatable) | Manage |
| `dv sites create-from-template <SLUG>` | Creates a website from a platform template. Its first version builds to a preview. | `--template`, `--name`, `--setting KEY=VALUE` | Manage |
| `dv sites template-update <SITE>` | A new version of a template website, with the template's current code and any changed settings. | `--setting KEY=VALUE`, `--notes` | Manage |
| `dv sites feeds <SITE>` | Replaces the module feeds a website reads. Issues a new read-only key; the site gets it with its next version. | `--feed` (repeatable; none removes all) | Manage |
| `dv sites env <SITE> KEY=VALUE ...` | Sets the website's own non-secret settings, applied with the next version. `KEY=` removes one. | | Manage |
| `dv sites pull <SITE> <folder>` | Downloads a version's code (default the live one) to change it. | `--version`, `--force` | Manage |
| `dv sites deploy <folder>` | Uploads the folder as a new version, builds it and prints its preview address. Not live until published, except a site's very first version. | `--site`, `--notes`, `--force` (upload even though the live site moved on since your pull) | Manage |
| `dv sites refresh <SITE> <VERSION>` | Checks a version that's building. | | View |
| `dv sites publish <SITE> <VERSION>` | **Live.** Puts a version live. Publishing an earlier version is the rollback. | | Publish |
| `dv sites archive <SITE> <VERSION>` | Takes a never-live version off the list. | `--reason` | Publish |
| `dv sites dns <SITE> [DOMAIN]` | Checks DNS now: the records to add, what DNS has, records to remove, and the certificate. | | View |
| `dv sites screenshot <SITE>` | Takes a new picture of the live landing page for the Websites tile. | | Manage |
| `dv sites domain add <SITE> <DOMAIN>` | Attaches a domain and prints the DNS records to add. | | Manage |
| `dv sites domain verify <SITE> <DOMAIN>` | Checks the ownership record and marks the domain verified. | | Manage |
| `dv sites domain remove <SITE> <DOMAIN>` | **Live.** Detaches a domain. Asks first (`--yes` skips). | | Manage |
| `dv sites route add <SITE> <DOMAIN> <PATH> <TARGET>` | **Live.** Serves a path on one website's domain with another of your websites, such as *yourcompany.com/updates*. | | Manage |
| `dv sites route remove <SITE> <DOMAIN> <PATH>` | **Live.** Stops that route. | | Manage |
| `dv sites route list <SITE>` | Routes on this site's domains. | | View |

## Good to know

- **Check the workspace first.** Every command that changes something acts in the workspace `dv dev status` shows.
- **`dv` and `platform` are the same tool.** Guides that write `platform modules deploy` mean `dv modules deploy`.
- **`validate`, `scan`, `rules`, `interfaces`, `version` and `guide` work offline**, so you can check a module before signing in.
- **`dv modules preview` and `dv dev token` show your sign-in.** The preview address carries your session token; don't paste it or the token anywhere others can see.
- **Very large modules** (over about 8 MB or 400 files) are deployed with the CLI rather than through an AI app. Uploads are limited to 50 MB.
- **Some commands in `dv --help` aren't for workspaces**, such as turning a module off for every workspace. Data Visions refuses them.


Source: https://datavisions.ai/docs/developer-tools/cli-command-reference
