# Install and sign in to the CLI

Install the Data Visions command line (dv) for your own user without administrator rights, sign in, check your workspace, update it and fix common problems.

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](article:9203acf3-a6ac-410b-8ada-73b8fa35654a).

## 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, `python3` from 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 pull` doesn'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:

1. 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_setup` tool. See [Marketplace: Connect your AI](article:488b0b95-e1d0-453c-9f15-e0ce2a91d746) if you haven't connected one yet.
2. Say which system you use: Windows, macOS or Linux.
3. 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 version
```

It 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>
```

1. The CLI checks it can reach Data Visions.
2. Type your **email** and **password** when asked. The password isn't shown as you type.
3. 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.
4. 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.
5. 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.
6. 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 logout
```

This 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.json` in your home folder for a change, then runs `dv dev status`.
- **It checks the workspace with you.** It reads the workspace and expiry from `dv dev status` back 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](article:6e6343d4-3801-4e7d-a21a-9722fb4ee89b).

## 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.
- **`dv` and `platform` are the same tool** in this package. Some guides write `platform`; type `dv`.
- **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](article:b6cb12bf-12ff-4632-afcd-f8fde03b149d).


Source: https://datavisions.ai/docs/developer-tools/install-and-sign-in-to-the-cli
