> 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/references/v1/interfaces/command-line-interface.md).

# CLI

DataOS CLI (`dataos-ctl`) is a command-line tool for interacting with DataOS. Use it to create, manage, and delete DataOS resources directly from your terminal. It works 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.

## Installation

Visit your DataOS instance home page, for example `https://dataossanbox.instance.dataos.cloud/`. Log in, then follow the **Setup DataOS CLI** instructions shown 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
```

A successful run downloads the CLI package for your OS and architecture, verifies its checksum, and prints the line you need to add to your `PATH`:

{% code overflow="wrap" %}

```bash
Downloading dataos-ctl-darwin-amd64.tar.gz ...
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
```

{% endcode %}

Add that `export` line to your shell startup file (`~/.zshrc` for Zsh, `~/.bash_profile` for Bash), then open a new terminal so the change takes effect.
{% endtab %}

{% tab title="Windows" %}
In **Setup DataOS CLI**, download the pre-built Windows package. Its name follows this pattern:

```
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" %}
**1. Set the destination and archive paths**

Replace the archive path with the actual location of your downloaded `.tar.gz` file:

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

**2. Create the installation directory**

```powershell
New-Item -ItemType Directory -Path $dest -Force | Out-Null
```

**3. Extract `dataos-ctl.exe`**

Windows versions that include `tar` can run:

```powershell
tar -xzf $archive -C $dest --strip-components=1 "windows-amd64/dataos-ctl.exe"
```

Then verify that the executable was extracted:

```powershell
Get-ChildItem $dest
```

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

**4. Add the CLI directory to the user `PATH`**

```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: ...` the first time, and `Already added.` on later runs.
{% endtab %}

{% tab title="Command Prompt" %}
**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`**

```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 %}

{% hint style="info" %}
The `PATH` change applies only to newly opened terminals. Close and reopen your terminal (PowerShell or Command Prompt), and fully restart VS Code, Cursor, or any other IDE, before using its integrated terminal.
{% endhint %}

Prefer the Windows interface over the command line? Add the same path manually:

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 %}

### Verify the installation

Confirm the binary is installed and on your `PATH`:

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

A successful installation prints the list of available 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="warning" %}
Use `--help`, not `version`, to confirm the install. Most commands, `version` included, first check whether the CLI has already been initialized. If it has not, they pause and ask whether to run the initialization prompt shown by `init`, instead of doing what you asked. `--help` is the one command that skips that check, so it is the reliable way to confirm the binary itself works, before you have connected it to any DataOS instance.
{% endhint %}

## Initialize the CLI

### dataos-ctl init

Running `init` creates a local tenant context: a named profile, stored on your machine, that records the DataOS instance domain and tenant identifier the CLI should talk to. Run it once per DataOS instance, before using any other command.

{% tabs %}
{% tab title="Syntax" %}

```bash
dataos-ctl init \
  [--flag-init] \
  [--context-name ${{context-name}}] \
  [--fully-qualified-domain-name ${{instance-fqdn}}] \
  [--tenant-identifier ${{tenant-id}}]
```

{% endtab %}

{% tab title="Example" %}

```bash
dataos-ctl init \
  --flag-init \
  --context-name my-tenant \
  --fully-qualified-domain-name dataossanbox.instance.dataos.cloud \
  --tenant-identifier engineering
```

{% endtab %}
{% endtabs %}

| Flag                            | Description                                                                                             | Type    | Required           |
| ------------------------------- | ------------------------------------------------------------------------------------------------------- | ------- | ------------------ |
| `--flag-init`                   | Initialize a new tenant context from flags instead of interactive prompts.                              | boolean | No                 |
| `--context-name`                | Local name to identify this DataOS® context.                                                            | string  | With `--flag-init` |
| `--fully-qualified-domain-name` | Fully qualified domain name of the DataOS® instance, without `https://`.                                | string  | With `--flag-init` |
| `--tenant-identifier`           | Tenant identifier in the DataOS® instance to associate with this context.                               | string  | With `--flag-init` |
| `--setup-config`                | Set up the config file and other static files in the home directory, without creating a tenant context. | boolean | No                 |
| `-h`, `--help`                  | Display help for this command.                                                                          | boolean | No                 |

Without `--flag-init`, the command walks you through the same three values interactively:

```bash
dataos-ctl init
```

```
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, for example `dataossanbox.instance.dataos.cloud`, not `https://dataossanbox.instance.dataos.cloud`. If you are unsure of your tenant name, ask your DataOS administrator.
{% endhint %}

**Adding another tenant context.** Run `dataos-ctl init` again any time you need to connect the same CLI to another instance, for example `my-tenant2` alongside `my-tenant`. Because a tenant context already exists, the CLI first asks whether to add a new one, then reuses the standard initialization prompt to collect the name, domain, and tenant identifier for it:

```
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" %}
That second prompt is not an error. It reuses the same initialization message shown during first-time setup. Answer `Y` again, and the CLI continues asking for the new tenant's name, domain, and tenant identifier.
{% endhint %}

### dataos-ctl tenant

Manage the tenant contexts stored locally on your machine: list which ones are configured, and switch the active one.

{% hint style="info" %}
`tenant` accepts the aliases `context`, `tnt`, `tent`, `tents`, `tt`, and `tenants`, so `dataos-ctl tenant list` and `dataos-ctl context list` are equivalent.
{% endhint %}

**`dataos-ctl tenant list`**: list every tenant context configured locally, and show which one is active.

```bash
dataos-ctl tenant list
```

```
  my-tenant2
  my-tenant3
* my-tenant

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

The `*` marks the active context. The 🔗 line shows the active context's instance FQDN, and the ⛺️ line shows its tenant identifier. `list` accepts the alias `ls`.

**`dataos-ctl tenant select`**: switch the active tenant context to a different, already-configured context.

{% tabs %}
{% tab title="Syntax" %}

```bash
dataos-ctl tenant select --name ${{context-name}}
```

{% endtab %}

{% tab title="Example" %}

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

{% endtab %}
{% endtabs %}

| Flag           | Description                           | Type    | Required |
| -------------- | ------------------------------------- | ------- | -------- |
| `-n`, `--name` | Name of the tenant context to select. | string  | Yes      |
| `-h`, `--help` | Display help for this command.        | boolean | No       |

Every command that follows in this page (`login`, `health`, `version`, `resource`, and so on) acts on whichever tenant context is currently active. Run `tenant select` first if you need to act on a different context.

## Log in

### dataos-ctl login

Authenticate the CLI against the currently active tenant context.

```bash
dataos-ctl login
```

| Flag           | Description                    | Type    | Required |
| -------------- | ------------------------------ | ------- | -------- |
| `-h`, `--help` | Display help for this command. | boolean | No       |

Running it opens a browser window for authentication. Complete the sign-in flow there, then return to your terminal.

## Check CLI and instance health

### dataos-ctl health

Check whether the CLI can reach and authenticate against the currently selected DataOS® instance. Use it as the first step when diagnosing connection or authentication issues.

```bash
dataos-ctl health
```

| Flag           | Description                    | Type    | Required |
| -------------- | ------------------------------ | ------- | -------- |
| `-h`, `--help` | Display help for this command. | boolean | No       |

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

`DataOS® CLI...OK` confirms the CLI binary is functioning. `DataOS® CK...OK` confirms the CLI reached the instance's control kernel.

## dataos-ctl version

Print the version of the CLI and, optionally, of the DataOS® instance it is connected to.

{% tabs %}
{% tab title="Syntax" %}

```bash
dataos-ctl version [--all] [--serverVersion] [--disableLogo] [--ogLogo]
```

{% endtab %}

{% tab title="Example" %}

```bash
dataos-ctl version --all --disableLogo
```

{% endtab %}
{% endtabs %}

| Flag                    | Description                                                  | Type    | Required |
| ----------------------- | ------------------------------------------------------------ | ------- | -------- |
| `-a`, `--all`           | Show both the CLI version and the server (instance) version. | boolean | No       |
| `-s`, `--serverVersion` | Show only the server (instance) version.                     | boolean | No       |
| `-d`, `--disableLogo`   | Suppress the ASCII logo banner.                              | boolean | No       |
| `-o`, `--ogLogo`        | Show the original logo variant.                              | boolean | No       |
| `-h`, `--help`          | Display help for this command.                               | boolean | No       |

```
$ dataos-ctl version --all --disableLogo
control-version : dataos-cli 3.16.16-dev a18e5f3e3eb9676d5b8813a60c157184e8276b97
product-version : instance-kernel-system - bootes - 0.12.0
product-version : instance-platform-shell - instance-platform-shell - 0.2.5
hub-fqdn        : dataossanbox.instance.dataos.cloud
hub-tcp-fqdn    : tcp.dataossanbox.instance.dataos.cloud
tenant-id       : engineering
```

Once the CLI is initialized, plain `dataos-ctl version` (without `--all` or `--serverVersion`) prints only the CLI's own version and needs no live connection to the instance. Add `--all` or `--serverVersion` to also query the instance for its version.

{% hint style="warning" %}
Before the CLI has been initialized, `version` does not print anything. It asks whether to run initialization instead, the same prompt described under [dataos-ctl init](#dataos-ctl-init). Run `dataos-ctl init` first, then use `version` freely.
{% endhint %}

***

## Quick reference

| Command                                                               | Description                                                                                                            |
| --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `dataos-ctl --help`                                                   | List available commands, and confirm the CLI is installed                                                              |
| `dataos-ctl init`                                                     | Initializes the DataOS® CLI                                                                                            |
| `dataos-ctl version`                                                  | Print the version number of DataOS®                                                                                    |
| `dataos-ctl login`                                                    | Login to the DataOS®                                                                                                   |
| `dataos-ctl tenant list`                                              | List DataOS® tenants                                                                                                   |
| `dataos-ctl tenant select`                                            | Select DataOS® Tenant                                                                                                  |
| `dataos-ctl health`                                                   | Health of DataOS®                                                                                                      |
| `dataos-ctl resource apply -f <manifest.yaml>`                        | Create or update a Resource from a manifest file                                                                       |
| `dataos-ctl resource get -t <type>`                                   | List Resources of a given type ([full reference](/references/v1/interfaces/command-line-interface/resource.md))        |
| `dataos-ctl depot types get`                                          | Get DataOS® depot type definitions                                                                                     |
| `dataos-ctl lakehouse table list --name <lakehouse> --namespace <ns>` | List tables in a Lakehouse namespace ([full reference](/references/v1/interfaces/command-line-interface/lakehouse.md)) |
| `dataos-ctl user apikey create`                                       | Generate a new API key ([full reference](/references/v1/interfaces/command-line-interface/user.md))                    |
| `dataos-ctl doc`                                                      | Generate markdown documentation for every command                                                                      |
| `dataos-ctl tui`                                                      | Open the DataOS® terminal UI                                                                                           |

The sections above cover `--help`, `init`, `tenant`, `login`, `health`, and `version` in full, in the order you would typically run them when setting up the CLI for the first time. What follows covers `depot`, `doc`, and `tui` in full. The `resource`, `lakehouse`, and `user` command groups are large enough to have their own reference pages, linked from the sections below.

***

## Manage resources

The `resource` command group is the command you'll use most: applying manifests, listing Resources, checking runtime status and logs, and controlling runnable Resources. See the [Resource commands](/references/v1/interfaces/command-line-interface/resource.md) reference for the full command set.

| Command                                               | What it does                                     |
| ----------------------------------------------------- | ------------------------------------------------ |
| `dataos-ctl resource apply -f <manifest.yaml>`        | Create or update a Resource from a manifest file |
| `dataos-ctl resource get -t <type>`                   | List Resources of a given type                   |
| `dataos-ctl resource delete -t <type> -n <name>`      | Delete a specific Resource                       |
| `dataos-ctl resource log -t <type> -n <name>`         | Get logs for a Resource                          |
| `dataos-ctl resource runtime run -t <type> -n <name>` | Trigger a run of a runnable Resource             |

→ [Full resource command reference](/references/v1/interfaces/command-line-interface/resource.md)

### dataos-ctl depot types get

A Depot defines how DataOS® connects to an external data source. Use `depot types get` to see which Depot types the instance supports, and what configuration each type requires.

{% tabs %}
{% tab title="Syntax" %}

```bash
dataos-ctl depot types get [--name ${{depot-type-name}}] [--details]
```

{% endtab %}

{% tab title="Example" %}

```bash
dataos-ctl depot types get --name jdbc --details
```

{% endtab %}
{% endtabs %}

| Flag                   | Description                                                         | Type    | Required |
| ---------------------- | ------------------------------------------------------------------- | ------- | -------- |
| `-n`, `--name`         | Name of the Depot type to get.                                      | string  | No       |
| `-d`, `--details`      | Return the full type definition, including secret and spec schemas. | boolean | No       |
| `-f`, `--manifestFile` | Path to a manifest file to resolve the query from.                  | string  | No       |
| `-h`, `--help`         | Display help for this command.                                      | boolean | No       |

```
$ dataos-ctl depot types get
     NAME      |         CREATED AT
---------------+-----------------------------
 abfss         | 2026-06-30T21:10:46.972746Z
 bigquery      | 2026-06-30T21:10:48.016676Z
 jdbc          | 2026-06-30T21:10:45.967629Z
 lakehouse     | 2026-06-30T21:10:48.742885Z
 postgresql    | 2026-06-30T21:10:44.633872Z
 s3            | 2026-06-30T21:10:45.103187Z
 snowflake     | 2026-06-30T21:10:49.465043Z
 ...
```

`get` accepts the aliases `ls` and `list`. Once a Depot manifest is created, apply it with `dataos-ctl resource apply -f <depot.yaml>`.

### Lakehouse tables

A `lakehouse`-type Depot backs a Lakehouse Resource, which stores Iceberg tables. Managing namespaces, tables, branches, schema, partitions, properties, and snapshots involves 38 commands. See the dedicated [Lakehouse commands](/references/v1/interfaces/command-line-interface/lakehouse.md) reference.

***

## Manage users

Creating users, issuing API keys, and assigning role tags involves 12 commands. See the dedicated [User commands](/references/v1/interfaces/command-line-interface/user.md) reference.

| Command                                                    | What it does                  |
| ---------------------------------------------------------- | ----------------------------- |
| `dataos-ctl user get --all`                                | List every user in the tenant |
| `dataos-ctl user apikey create`                            | Generate a new API key        |
| `dataos-ctl user tag add --id <user-id> --tags <role-tag>` | Assign a role to a user       |

→ [Full user command reference](/references/v1/interfaces/command-line-interface/user.md)

***

## Utilities

### dataos-ctl doc

Generate Markdown documentation for every command in the `dataos-ctl` CLI, based on the version currently installed.

```bash
dataos-ctl doc
```

| Flag           | Description                    | Type    | Required |
| -------------- | ------------------------------ | ------- | -------- |
| `-h`, `--help` | Display help for this command. | boolean | No       |

{% hint style="warning" %}
`doc` exposes no flag to redirect its output location and writes files relative to the current working directory. Run it inside an empty directory so the generated files do not mix with unrelated ones.
{% endhint %}

### dataos-ctl tui

Launch an interactive, full-screen terminal UI for browsing DataOS® resources, as an alternative to issuing individual `dataos-ctl` commands.

```bash
dataos-ctl tui
```

| Flag           | Description                    | Type    | Required |
| -------------- | ------------------------------ | ------- | -------- |
| `-h`, `--help` | Display help for this command. | boolean | No       |

{% hint style="info" %}
`tui` requires an interactive terminal (TTY). Running it in a non-interactive shell or CI pipeline produces no usable output.
{% endhint %}

***

## Troubleshooting

**Checksum mismatch**

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

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

**`command not found` after installing**

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.

**Login error: duplicate `https://` in the URL**

```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, without the `https://` prefix.

***

## Related references

* [Resource commands](/references/v1/interfaces/command-line-interface/resource.md): apply, inspect, run, and remove any Resource type.
* [Lakehouse commands](/references/v1/interfaces/command-line-interface/lakehouse.md): manage Iceberg tables, branches, schema, and snapshots.
* [User commands](/references/v1/interfaces/command-line-interface/user.md): manage users, API keys, and role tags.


---

# 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/references/v1/interfaces/command-line-interface.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.