> For the complete documentation index, see [llms.txt](https://v2.dataos.info/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://v2.dataos.info/build/v1/get-started/prerequisites/cli-setup.md).

# CLI setup

The DataOS CLI is a command-line tool for interacting with DataOS. It provides a consistent experience on macOS, Linux, and Windows.

## Prerequisites

* **`curl`** (macOS and Linux). Check with `curl --version`. If it is missing, get it from [curl.se](https://curl.se/download.html) or your package manager.
* **`tar`** (Windows). Windows 10 version 1803 or later, and Windows 11, include `tar.exe` by default. Check with `tar --version` in PowerShell or Command Prompt. If it is missing, install a tar-compatible tool such as 7-Zip and use it to extract the archive instead, or upgrade Windows.
* **Access to a DataOS instance.** If you do not have it, ask your DataOS administrator to invite you.

## 1. Install the CLI

Open your DataOS instance home page, for example `https://dataossanbox.instance.dataos.cloud/`, log in, and follow the **Setup DataOS CLI** instructions on the landing page.

{% tabs %}
{% tab title="macOS and Linux" %}
Copy the install command from the **Setup DataOS CLI** section. It pipes the installer through your bearer token:

```sh
curl --request GET 'https://<instance-url>/home/dataos/cli-dev-v2/install.sh' \
  --header 'Authorization: Bearer <your-token>' | sh
```

**Output:** A successful installation prints output similar to the following:

<pre class="language-bash" data-overflow="wrap"><code class="lang-bash">  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  4326  100  4326    0     0   2801      0  0:00:01  0:00:01 --:--:--  2800
<strong>Downloading dataos-ctl-darwin-amd64.tar.gz ... 
</strong>  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100 45.5M  100 45.5M    0     0  4780k      0  0:00:09  0:00:09 --:--:-- 9770k
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100    97  100    97    0     0     70      0  0:00:01  0:00:01 --:--:--    70
dataos-ctl-darwin-amd64.tar.gz download complete!
Checksum dataos-ctl-darwin-amd64.tar.gz: OK

Add the dataos-ctl to your path with:
export PATH=$PATH:$HOME/.dataos/v2/bin 
</code></pre>

Add the directory to your `PATH`, then verify the installation:

{% code overflow="wrap" %}

```bash
dataos-ctl --help
```

{% endcode %}

The command prints the available DataOS CLI commands:

{% code overflow="wrap" %}

```bash
DataOS® command line application to use the DataOS®.

Usage:
  dataos-ctl [command]

Available Commands:
  cloudevents Manage DataOS® cloud events
  collation   Interact with the Collation Service in the DataOS®
  completion  Shell completion for the given shell (zsh or bash)
  depot       Manage DataOS® depots
  develop     Manage DataOS® Development
  doc         Generate markdown documentation for every command
  domain      Manage domains in the DataOS®
  forge       Manage MDC Forge
  health      Health of DataOS®
  help        Help about any command
  init        Initializes the DataOS® CLI
  lakehouse   Manage DataOS® Lakehouse
  login       Login to the DataOS®
  operate     Operate the DataOS®
  resource    Manage resources in the DataOS®
  role        Manage DataOS® Roles
  tenant      Manage DataOS® Tenants
  tui         Terminal UI of the DataOS
  user        Manage DataOS® Users
  version     Print the version number of DataOS®
  view        View DataOS® Applications and Resources

Flags:
  -h, --help                 help for dataos-ctl
      --tls-allow-insecure   Allow insecure TLS connections

Use "dataos-ctl [command] --help" for more information about a command.
```

{% endcode %}
{% endtab %}

{% tab title="Windows" %}
Use this method on Windows.

First, open your DataOS instance home page and sign in. In **Setup DataOS CLI**, download the pre-built Windows package. Its name follows this pattern (sample file name):

```bash
dataos-cli--aa.bb.cc-windows-amd64.tar.gz
```

Use either PowerShell or Command Prompt to extract the package and add it to your `PATH`.

{% tabs %}
{% tab title="PowerShell" %}
Open **Windows PowerShell**, then run the following commands. Replace the `$archive` value with the complete path to your downloaded file. For example: `$archive = "C:\Users\John Doe\Downloads\dataos-cli--01.23.45-windows-amd64.tar.gz"`.

```powershell
$dest = "$env:LOCALAPPDATA\Programs\dataos-cli\bin"
$archive = "<path-to-downloaded-file>\dataos-cli--aa.bb.cc-windows-amd64.tar.gz"
```

Then run the following commands. Windows versions that include `tar` can run:

{% code overflow="wrap" %}

```powershell
New-Item -ItemType Directory -Path $dest -Force | Out-Null
tar -xzf $archive -C $dest --strip-components=1 "windows-amd64/dataos-ctl.exe"
Get-ChildItem $dest
```

{% endcode %}

The command lists `dataos-ctl.exe` after extraction.

Now for adding the CLI to PATH, run the following command in the same PowerShell window:

```powershell
$dir = "$env:LOCALAPPDATA\Programs\dataos-cli\bin"
$old = [Environment]::GetEnvironmentVariable('Path', 'User')

if ($old -split ';' -contains $dir) {
    "Already added."
} else {
    [Environment]::SetEnvironmentVariable('Path', ($old.TrimEnd(';') + ';' + $dir), 'User')
    "Added: $dir"
}
```

The command prints `Added: ...` or `Already added.`.
{% endtab %}

{% tab title="Command Prompt" %}
Open **Command Prompt**, then use this sequence.

**1. Set the destination and archive paths.** Replace the archive path with the actual location of your downloaded `.tar.gz` file:

```bat
set "DEST=%LOCALAPPDATA%\Programs\dataos-cli\bin"
set "ARCHIVE=C:\Users\John Doe\Downloads\dataos-cli--01.23.45-windows-amd64.tar.gz"
```

**2. Create the installation directory:**

```bat
mkdir "%DEST%"
```

{% hint style="info" %}
If the folder already exists, `mkdir` prints an error you can ignore.
{% endhint %}

**3. Extract `dataos-ctl.exe`.** Windows versions that include `tar` can run:

```bat
tar -xzf "%ARCHIVE%" -C "%DEST%" --strip-components=1 "windows-amd64/dataos-ctl.exe"
```

Then verify that the executable was extracted:

```bat
dir "%DEST%"
```

You should see `dataos-ctl.exe` listed.

**4. Add the CLI directory to the user PATH.** For Command Prompt, use:

```bat
setx PATH "%PATH%;%LOCALAPPDATA%\Programs\dataos-cli\bin"
```

You should get a message similar to `SUCCESS: Specified value was saved.`

{% hint style="warning" %}
`setx` changes the `PATH` for new Command Prompt windows, not the current one.
{% endhint %}
{% endtab %}
{% endtabs %}

Once it's done, close your terminal completely. Open a new PowerShell or Command Prompt window, then run:

```
dataos-ctl --help
```

The command prints the available DataOS CLI commands:

{% code overflow="wrap" %}

```bash
DataOS® command line application to use the DataOS®.

Usage:
  dataos-ctl [command]

Available Commands:
  cloudevents Manage DataOS® cloud events
  collation   Interact with the Collation Service in the DataOS®
  completion  Shell completion for the given shell (zsh or bash)
  depot       Manage DataOS® depots
  develop     Manage DataOS® Development
  doc         Generate markdown documentation for every command
  domain      Manage domains in the DataOS®
  forge       Manage MDC Forge
  health      Health of DataOS®
  help        Help about any command
  init        Initializes the DataOS® CLI
  lakehouse   Manage DataOS® Lakehouse
  login       Login to the DataOS®
  operate     Operate the DataOS®
  resource    Manage resources in the DataOS®
  role        Manage DataOS® Roles
  tenant      Manage DataOS® Tenants
  tui         Terminal UI of the DataOS
  user        Manage DataOS® Users
  version     Print the version number of DataOS®
  view        View DataOS® Applications and Resources

Flags:
  -h, --help                 help for dataos-ctl
      --tls-allow-insecure   Allow insecure TLS connections

Use "dataos-ctl [command] --help" for more information about a command.
```

{% endcode %}

{% hint style="info" %}
The PATH change applies only to newly opened terminals. Restart VS Code, Cursor or other IDE completely before using its integrated terminal.
{% endhint %}

If you prefer the Windows interface, use the following steps to add PATH using Windows settings:

1. Press `Win + R`, enter `sysdm.cpl`, then press Enter.
2. Select **Advanced** → **Environment Variables**.
3. Under **User variables**, select **Path** → **Edit** → **New**.
4. Add `C:\Users\<your-username>\AppData\Local\Programs\dataos-cli\bin`.
5. Select **OK** in each window, then open a new terminal.
   {% endtab %}
   {% endtabs %}

{% hint style="warning" %}
Use `dataos-ctl --help` to confirm the install, not `dataos-ctl version`. Before the CLI is initialized, `version` does not print anything, it asks whether to run the initialization prompt shown below instead. `--help` is the one command that skips that check.
{% endhint %}

## 2. Initialize the DataOS Tenant

Connect the CLI to your instance:

```sh
dataos-ctl init
```

The CLI runs a short interactive prompt. You give it a tenant context name, the instance domain, and your tenant identifier:

```
INFO[0000] 🚀 initialization...                          
INFO[0000] The DataOS® is not initialized, do you want to proceed with initialization? (Y,n)  
-> Y
Please enter a name for the current DataOS® Context?                    
-> my-tenant
Please enter the Fully Qualified Domain Name of the DataOS® instance?   
-> dataossanbox.instance.dataos.cloud
Please enter the Tenant Identifier to use for the DataOS® instance?     
-> engineering
entered DataOS®: my-tenant : dataossanbox.instance.dataos.cloud : engineering
🚀 initialization...complete
```

{% hint style="warning" %}
Enter the **tenant identifier** in lowercase, and enter the Fully Qualified Domain Name **without** the `https://` prefix. If you are unsure of your tenant name, ask your DataOS administrator.
{% endhint %}

Run `dataos-ctl init` again anytime to add another tenant context (for example, staging and production). When you do, the CLI first asks whether to add a new context, then walks you through the same name/domain/tenant-identifier prompts shown below:

```
The DataOS® is already initialized, do you want to add a new tenant context? (Y,n)
-> Y
🚀 initialization...
The DataOS® is not initialized, do you want to proceed with initialization? (Y,n)
-> Y
```

{% hint style="info" %}
The second prompt reuses the standard initialization message. Answer `Y` again to continue adding the new context.
{% endhint %}

To switch between tenant/contexts, use:

{% code overflow="wrap" expandable="true" %}

```bash
dataos-ctl tenant select --name my-tenant2
```

{% endcode %}

To list all configured tenant contexts, run `dataos-ctl tenant list`. The active context is marked with `*`:

```
dataos-ctl tenant list

  my-tenant2
  my-tenant3
* my-tenant

🔗...https://dataossanbox.instance.dataos.cloud
⛺️...engineering
```

To explore commands around tenant, run `dataos-ctl tenant --help`.

{% hint style="info" %}
`tenant` accepts the following aliases, so `dataos-ctl context list`, `dataos-ctl tnt list`, and `dataos-ctl tenant list` are equivalent:

```
Aliases:
  tenant, context, tnt, tent, tents, tt, tenants
```

{% endhint %}

## 3. Log in

```sh
dataos-ctl login
```

This opens a browser for authentication. Complete the flow and return to your terminal.

## 4. Check CLI and instance health

```sh
dataos-ctl health
```

`health` confirms the CLI can reach your tenant

{% code overflow="wrap" %}

```bash
➜  ~ dataos-ctl health
INFO[0000] 🏥...                                         
INFO[0001] 🏥...complete                                 
DataOS® CLI...OK
DataOS® CK...OK
hub-fqdn        : dataossanbox.instance.dataos.cloud
hub-tcp-fqdn    : tcp.dataossanbox.instance.dataos.cloud
tenant-id       : engineering
```

{% endcode %}

To browse commands, run `dataos-ctl --help`. For help on a specific command, run `dataos-ctl [command] --help`.

## Troubleshooting

<details>

<summary>Checksum mismatch</summary>

```bash
sha256sum: WARNING: 1 computed checksum did NOT match
```

The download is corrupted. Re-download the package for your OS and architecture and retry.

</details>

<details>

<summary><code>command not found</code> after installing</summary>

Confirm the CLI's install directory is on your `PATH`. On macOS and Linux, that is `$HOME/.dataos/v2/bin`. On Windows, that is `$env:LOCALAPPDATA\Programs\dataos-cli\bin`.

```sh
echo $PATH
```

If the directory is missing from the output, add the matching `export PATH=...` line to your shell startup file (`~/.zshrc` for Zsh, `~/.bash_profile` for Bash), then open a new terminal.

</details>

<details>

<summary>Login error: duplicate <code>https://</code> in the URL</summary>

```bash
ERRO Post "https://https//dataossanbox.instance.dataos.cloud/...": lookup https: no such host
```

You included `https://` when entering the domain during `init`. Re-run `dataos-ctl init` and enter the domain only.

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://v2.dataos.info/build/v1/get-started/prerequisites/cli-setup.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.