> 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/readme/cli-setup.md).

# CLI Setup

The DataOS Command Line Interface (CLI), `dataos-ctl`, is the primary tool you use to apply, manage, and inspect DataOS Resources such as Secrets, Depots, and Vulcan deployments. Install and verify the CLI before moving to any other step.

* **`curl` installed** (macOS and Linux only). Verify with:

  ```sh
  curl --version
  ```

  If it is not installed, download it from [curl.se](https://curl.se/download.html) or use your system's package manager.
* **DataOS instance access**: Make sure you have access to a DataOS instance. If not, ask your DataOS administrator to invite you.

Once these are ready, continue with the setup steps below. You will install the CLI, connect it to your DataOS context, log in, and verify the setup.

{% stepper %}
{% step %}

## Install the CLI

Visit your DataOS instance home page, for example, `https://training-007.dataos.cloud/` . Then log in, and follow the **Setup DataOS CLI** instructions shown on the landing page.

{% embed url="<https://app.arcade.software/share/4lD4oun5g7ChGaJtCBjH>" %}

{% tabs %}
{% tab title="Via curl" %}
Copy the commands shown in the **Setup DataOS CLI** section of the landing page and run them in your terminal. The command will followed with the bearer token(sample):

```sh
# Download and install the DataOS CLI
curl -request GET 'https://training-007.dataos.cloud/home/dataos/cli-dev-v2/install.sh' --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IjY4YjkZTQ2NDg2NjkifQ.eyJpc3MiOiJodHRwczovL3BhY2lmaWMtMDUxNDI2LmRhdGFvcy5jbG91ZC9vaWRjIiwic3ViIjoiQtVTJZemd4Wmkwek4yVTBMbkERVjhvYCnkvkRRdFlqSXlNeTA0TUdVek1XWXhPVGxoTjJJU0RuUnRaR010YldsamNtOXpiMlowIiwiYXVkIjoiZGF0YW9zX2dlbmVyaWMiLCJleHAiOjE3ODE5NDIyMjQsImlhdCI6MTc4MTg1NTgyNCwiYXRfaGFzaCI6IlZjWTk3X1hlSEN2ZTZPc1Vhb2xKcEEiLCJlbWFpbCI6ImFhZGl0eWEuc29uaUB0bWvIiwiZW1haWxfdmVyaWZpZWQiOnRydWUsImdyb3VwcyI6WyJlNjg1MTRlMy03YzE5LTRmYzAtOWEyNS02ZWUzZjc1MmUyMjQiLCJkMzAzOTNkNC0xOWFmLTRiYTEtYjM0Zi1mZjdjNzUxMjg1MGMiXSwibmFtZSI6IkFhZGl0eWEgU29uaSIsImZlZGVyYXRlZF9jbGFpbXMiOnsiY29ubmVjdG9yX2lkIjoidG1kYy1taWNyb3NvZnQiLCJ1c2VyX2lkIjoiZDJlNmM4MWYtMzdlNC00ZDQ0LWIyMjMtODBlMzFmMTk5YTdiIn19.CoONbZtP-YMuS4NxqrWlH6_oPyduxSe1tmnH-JoQ4_JiYaxEDsTe3Gr7qjavhNP3xGhVpTPqSUHNrUPZlbkQk-01skK3kgGBdytWmxZc136sMzn4fcVvoq-WTpe2NN773qY41E_f7BujCaqZRDq0GRwWTNQIK1bdpwfO3mkkV9Vug5-XGoMSFQ_dLuk_cJ5mLNDOCFMLnzqLPwCQ7P58a4IQ60spPSfj_qWLgzHBDPd6KDMaDTdF9umMhsOY9LnXIeOQ0gwg_-nlf1eL1bVwAn9G2ivskrG3aHHSRytwHmMsUkKy07d2RcMPSoH2KbvHWW6_k26qDYwBSRSdkMdmmA' | sh

# Verify the installation
dataos-ctl version
```

A successful install prints:

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

```bash
    ____        __        ____  _____
   / __ \____ _/ /_____ _/ __ \/ ___/
  / / / / __ `/ __/ __ `/ / / /\__ \ 
 / /_/ / /_/ / /_/ /_/ / /_/ /___/ / 
/_____/\__,_/\__/\__,_/\____//____/  
                                     
control-version : dataos-cli 3.xx.x.........
```

{% endcode %}
{% endtab %}

{% tab title="Via pre-built package" %}
Use this method if you prefer to download and install the binary manually, or if your network does not allow piping scripts from the internet.

**1. Select your OS and architecture**

On the **Setup DataOS CLI** section of the landing page, select your operating system and processor architecture, then download the package.

| Operating System | Processor                   | Architecture    |
| ---------------- | --------------------------- | --------------- |
| macOS            | Intel                       | `darwin-amd64`  |
| macOS            | Apple Silicon (M1/M2/M3/M4) | `darwin-arm64`  |
| Linux            | Intel/AMD 64-bit            | `linux-amd64`   |
| Linux            | ARM 64-bit                  | `linux-arm64`   |
| Linux            | Intel 32-bit                | `linux-386`     |
| Windows          | 64-bit                      | `windows-amd64` |
| Windows          | 32-bit                      | `windows-386`   |

**2. Run the install commands**

The commands shown on the setup page follow this pattern (file names reflect your selected OS and architecture):

```sh
cat dataos-cli-{{OS}}-{{ARCH}}-cli-dev-v2.tar.gz.sha256sum | sha256sum -c - &&
sudo rm -f /usr/local/bin/dataos-ctl &&
sudo tar -xzf dataos-cli-{{OS}}-{{ARCH}}-cli-dev-v2.tar.gz -C /usr/local/bin/ --strip-components=1 &&
sudo chmod +x /usr/local/bin/dataos-ctl &&
dataos-ctl version
```

Example for macOS with Apple Silicon:

```sh
cat dataos-cli-darwin-arm64-cli-dev-v2.tar.gz.sha256sum | sha256sum -c - &&
sudo rm -f /usr/local/bin/dataos-ctl &&
sudo tar -xzf dataos-cli-darwin-arm64-cli-dev-v2.tar.gz -C /usr/local/bin/ --strip-components=1 &&
sudo chmod +x /usr/local/bin/dataos-ctl &&
dataos-ctl version
```

A successful install prints:

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

```bash
    ____        __        ____  _____
   / __ \____ _/ /_____ _/ __ \/ ___/
  / / / / __ `/ __/ __ `/ / / /\__ \ 
 / /_/ / /_/ / /_/ /_/ / /_/ /___/ / 
/_____/\__,_/\__/\__,_/\____//____/  
                                     
control-version : dataos-cli 3.xx.x.........
```

{% endcode %}
{% endtab %}
{% endtabs %}
{% endstep %}

{% step %}

## Initialize the DataOS context

After installation, run the init command to connect the CLI to your DataOS instance:

```sh
dataos-ctl init
```

The CLI walks you through a short interactive prompt. Here is an example session:

```bash
INFO[0000] The DataOS® is not initialized, do you want to proceed with initialization? (Y,n)
->Y

INFO[0005] Please enter a name for the current DataOS® Context?
->my-context

INFO[0012] Please enter the Fully Qualified Domain Name of the DataOS® instance?
->your-org.dataos.app

INFO[0037] Please enter the Tenant Identifier to use for the DataOS® instance?
->engineering

INFO[0041] entered DataOS®: my-context : your-org.dataos.app : engineering

INFO[0041] 🚀 initialization...complete
```

{% hint style="warning" %}
**Tenant Identifier** is the name of the tenant you belong to within the DataOS context. Always enter the tenant name in **lowercase**. If you are unsure of your tenant name, reach out to your DataOS administrator.
{% endhint %}

If you have multiple DataOS contexts (e.g., staging and production), you can run `dataos-ctl init` again to add another context and switch between them using the CLI.
{% endstep %}

{% step %}

## Log in

After the context is initialized, log in to your DataOS account:

```sh
dataos-ctl login
```

This opens a browser window for authentication. After completing the login flow, return to your terminal. You are authenticated.
{% endstep %}

{% step %}

## Verify the installation

Run both commands to confirm the CLI is installed and healthy:

```sh
dataos-ctl version
dataos-ctl health
```

`version` should print `cli-dev-v2`. `health` confirms that the CLI can reach your DataOS context successfully.
{% endstep %}
{% endstepper %}

To explore available CLI commands and their options, run:

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

```shellscript
dataos-ctl --help
dataos-ctl <command> --help
```

{% endcode %}

## Troubleshooting

<details>

<summary>Checksum mismatch</summary>

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

The downloaded package is corrupted. Re-download the package for your OS and architecture and try again.

</details>

<details>

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

If `dataos-ctl version` returns `command not found`, verify that `/usr/local/bin` is in your `PATH`:

```sh
echo $PATH
```

If it is missing, add it:

```sh
export PATH=$PATH:/usr/local/bin
```

To make this permanent, add the line above to your shell's startup file:

* Zsh: `~/.zshrc`
* Bash: `~/.bash_profile`

</details>

<details>

<summary><code>permission denied</code></summary>

Ensure you are running the install commands with `sudo`.

</details>

<details>

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

If you see this error after running `dataos-ctl login`:

```
ERRO[0000] Post "https://https//your-org.dataos.app/...": dial tcp: lookup https: no such host
```

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

```
->your-org.dataos.app
```

</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/readme/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.