The Data Visions command line, dv, lets you work with your workspace from a terminal: check modules out and in, check and deploy them, run your modules' actions, build reports and manage your websites. It acts as you, in one workspace at a time, with exactly what your role allows. It can't do anything you couldn't do in the app.
This page covers installing it, signing in and keeping it current. For what each command does, see CLI command reference.
What you need
- Python 3.11 or newer, installed for your own user. On Windows, use the python.org installer with Install for all users unticked, or Python from the Microsoft Store. On macOS and Linux,
python3from your usual source. No administrator rights are needed. - A Data Visions login. Everyone in a workspace can sign in. Building and deploying modules needs a Workspace Admin; other people can run their modules' actions and build reports.
- Git (optional, recommended). Checking a module out makes a Git repository when Git is installed. Without it, the check-out works but
dv modules pulldoesn't.
The package is called data-visions-module-sdk. It installs two identical commands, dv and platform. Use dv: other software on your computer can own the name platform.
Get your install steps
The CLI is downloaded with a personal link that works for 15 minutes and only for you. To get one:
- In Claude, ChatGPT, Cursor or another AI app connected to your workspace, ask: "Set up the Data Visions CLI on my computer". The app uses the connector's
cli_setuptool. See Marketplace: Connect your AI if you haven't connected one yet. - Say which system you use: Windows, macOS or Linux.
- You get the download link, the install lines, the check, the sign-in line with your address already filled in, and how to update.
If you don't use an AI app, ask Data Visions for the install steps.
Install it
The steps put the CLI in its own folder in your home folder, so nothing else on your computer changes. Run the lines your setup steps give you, one at a time.
Windows (in Command Prompt):
py -m venv "%USERPROFILE%\data-visions-cli"
"%USERPROFILE%\data-visions-cli\Scripts\python.exe" -m pip install --upgrade "<your download link>"macOS and Linux (in Terminal):
python3 -m venv ~/data-visions-cli
~/data-visions-cli/bin/python -m pip install --upgrade "<your download link>"The dv command is then at %USERPROFILE%\data-visions-cli\Scripts\dv.exe on Windows, or ~/data-visions-cli/bin/dv on macOS and Linux. It isn't added to your PATH, so either call it by that full path or activate the folder first (%USERPROFILE%\data-visions-cli\Scripts\activate on Windows, source ~/data-visions-cli/bin/activate elsewhere). The examples on this page write plain dv.
If the link has expired, the download says so. Ask your AI app for a new one.
Check the install
dv versionIt should print data-visions-module-sdk and a version number, such as data-visions-module-sdk 0.34.0. If it prints anything else, you are running a different program: use the full path above.
Sign in
Use the address from your setup steps. It's the sign-in line cli_setup gave you. You can also work it out from your workspace's connector address (System settings › Marketplace › Connect your AI › Copy): it's the same address without /mcp at the end. Always give the address; don't rely on a default.
dv dev connect --url <your-address>- The CLI checks it can reach Data Visions.
- Type your email and password when asked. The password isn't shown as you type.
- If you belong to several workspaces, it lists them. Type the number of the one you want. Invitations you haven't answered are mentioned; answer them in the app.
- If your account uses two-factor sign-in, type the code from your authenticator app, or one of your recovery codes. You get three tries.
- If your workspace requires two-factor sign-in and you haven't set it up, the CLI shows a QR code in the terminal. Scan it with an authenticator app and type the code it shows. It then shows your recovery codes once: store them somewhere safe.
- It shows your role and the workspace you're in, then saves the session.
To go straight to one workspace, add --tenant <workspace-slug>. You must be a member of it.
Where the session is kept
The session is saved in your home folder, at .data-visions/session.json. It holds the address, a sign-in token, who you are and which workspace. Every later command uses it.
It's a live credential: never share it, commit it or paste it anywhere. The session ends when its token expires; then you sign in again.
Check who and where you are
dv dev status| Line | Shows |
|---|---|
| Platform URL | The address you signed in to |
| User | Your name and email |
| Tenant | The workspace's name and slug |
| Expires | When the session stops working, and how long is left |
Read the workspace before you change anything. A deploy, a check-in or an action always lands in the workspace shown here.
Switch workspace
If you belong to more than one workspace:
dv dev tenant <workspace-slug>The session is reissued for that workspace. If the slug isn't one of yours, the CLI lists the ones you have. If that workspace requires two-factor sign-in, you're asked for a code.
Sign out
dv dev logoutThis deletes the saved session from your computer. Your personal access tokens and connected AI apps aren't affected.
Using the CLI from a coding agent
Coding agents such as Claude Code and Cursor can run dv for you. They follow the same rules as any other way of using Data Visions: the agent acts as you, and it never handles your password.
- The agent opens the sign-in for you. When the session is missing or expired, the agent starts
dv dev connect --url <your-address>in a terminal window on your screen. You type your email, password and code there; the agent never sees them. - It waits for the session. It watches
.data-visions/session.jsonin your home folder for a change, then runsdv dev status. - It checks the workspace with you. It reads the workspace and expiry from
dv dev statusback to you before deploying or changing anything. - Don't paste passwords, codes or the session file into the chat. If an agent asks for them, say no and have it open the sign-in instead.
On Windows, an agent can open the sign-in window like this (with your own address):
Start-Process powershell -ArgumentList '-NoExit','-Command',"& '$env:USERPROFILE\data-visions-cli\Scripts\dv.exe' dev connect --url <your-address>"For building modules with an agent, see Build a module with a coding agent, start to finish.
Signing in from a script
dv dev connect also takes --email and reads the password from standard input with --password-stdin, or from the PLATFORM_PASSWORD environment variable. Use these only for your own unattended jobs, never to hand a password to an AI agent. Two-factor sign-in still asks for a code.
The CLI signs in with your email and password. It doesn't take a personal access token.
Update the CLI
Ask your AI app for the CLI setup steps again to get a new link, then run the same pip install --upgrade line with it. Your session is kept. Check with dv version.
Troubleshooting
| You see | What it means | What to do |
|---|---|---|
No dev session | You haven't signed in on this computer, or you signed out | dv dev connect --url <your-address> |
Session expired | The session's token has run out | Sign in again |
Cannot reach server | Wrong address, or no network | Check the address from your setup steps |
Authentication failed | Wrong email or password | Try again, or reset your password in the app |
You are signed in to 'x', not 'y' | --tenant named a workspace your login didn't enter | Sign in without --tenant and pick from the list, or ask to be added to that workspace |
The wrong workspace in dv dev status | You picked another workspace at sign-in | dv dev tenant <workspace-slug> |
| A deploy is refused as needing an admin | Your role isn't Workspace Admin | Ask a Workspace Admin for the role |
dv version prints something else, or No module named ... | Another program owns the command name | Call dv by its full path in the CLI's folder |
| The download says the link has expired | The 15 minutes are up | Ask your AI app for the setup steps again |
Good to know
- The CLI is never more than you. It has your role in one workspace, the same as the app.
- Nothing in the setup needs administrator rights. Python and the CLI both install for your user only.
dvandplatformare the same tool in this package. Some guides writeplatform; typedv.- Sign out on shared computers with
dv dev logout. - Prefer the connector for everyday questions. The CLI is best for files on disk: large modules, check-outs and websites. See Developer tools: the connector, the CLI and the SDK.