> For the complete documentation index, see [llms.txt](https://developer.collibra.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.collibra.com/cli/cli.md).

# Collibra CLI

The Collibra CLI is a unified command-line tool that packages API calls, allowing you to manage your Collibra products directly from the terminal. You can use it to interact with your environment manually or integrate it into automation workflows.

The CLI is a shared utility that supports multiple Collibra features. Once installed and configured, you can use it to perform actions such as registering AI model versions and managing data contracts, among others.

## Prerequisites

* You have a Collibra account with the permissions required for the actions you want to perform.

### Requirements for organizations using SSO

If your organization uses SSO to sign in to Collibra, your authentication path depends on your SSO type.

{% tabs %}
{% tab title="OAuth" %}
The CLI supports OAuth 2.0 authentication directly. Your administrator must first register an OAuth application in your Collibra environment and provide you with a client ID and a client secret.

**Prerequisite**: You have a global role with the **Product Rights** > **System administration** global permission.

1. In **Settings**, click **OAuth applications**.
2. Click **+ New Application**.
3. In the **User Application** section, click **Register user application**.
4. Enter the required information:
   * **Application name**: A unique name to identify this OAuth application in your Collibra environment.
   * **Redirect URIs**: The URIs to which Collibra redirects you after authentication. The CLI uses this URI to receive the authorization code. Click **+ Add URI** to specify multiple redirect URIs.
   * **Enable Proof Key for Code Exchange (PKCE)**: Adds a security layer that protects the authorization code against interception attacks. It is switched on by default. Switch it off only if your OAuth client configuration requires it.
5. Click **Register**.

The client ID and client secret are shown in a dialog box. Save them, you need them to configure the CLI.
{% endtab %}

{% tab title="SAML2" %}
Your SSO credentials cannot be used to authenticate with the CLI. You need a dedicated local account instead.

1. Ask your Collibra administrator to create a dedicated user account directly in your Collibra environment, bypassing SSO.
2. Assign the permissions required for the actions you want to perform to the new account.
3. When the account is created, you receive an invitation email. Click the link in the email to activate the account and set your password.
4. Use these dedicated local credentials when authenticating with the CLI.
   {% endtab %}
   {% endtabs %}

## Install the CLI

{% stepper %}
{% step %}
Download the CLI binary from [GitHub](https://github.com/collibra/collibra-cli-releases) and extract it. Choose the file for your operating system and processor:

* **Windows amd64**: for most Windows machines.
* **Windows arm64**: for Surface and similar devices.
* **Linux amd64**: for most Linux machines.
* **Linux arm64**: for Linux machines with ARM architecture.
* **darwin-macos all**: for Mac.
  {% endstep %}

{% step %}
Open your terminal or command prompt and navigate to the folder where you saved the downloaded file:

* Windows: `cd C:\Users\YourUserName\Downloads`
* Linux or Mac: `cd ~/Downloads`
  {% endstep %}

{% step %}
Extract the binary:

* Windows: `tar -xf collibra-x.x.x-windows_xxx64.zip`
* Linux: `tar -xf collibra-x.x.x-linux_xxx64.tar.gz`
* Mac: `unzip collibra-x.x.x-darwin-macos_all.zip`
  {% endstep %}

{% step %}
Mac only: if your Mac prevents the binary from running because the developer is not verified, allow it through macOS security:

1. Go to **System Settings** → **Privacy & Security**.
2. Find the message about the `collibra` file being blocked and click Open Anyway.

Alternatively, run the following command to remove the quarantine flag: `xattr -d com.apple.quarantine <file>`.

The current version is pending an official Apple signing key. This is a standard macOS security prompt and does not indicate a problem with the file.
{% endstep %}

{% step %}
Confirm the binary works by running it without any arguments:

* Windows: `.\collibra`
* Linux or Mac: `./collibra`

A help message is shown, listing the available commands.
{% endstep %}
{% endstepper %}

## Configure the CLI

Before you can run any commands, set the environment variables so the CLI can connect to your Collibra environment. Replace the placeholder values with your actual credentials. The variables you need depend on your authentication method.

### Basic auth

{% tabs %}
{% tab title="Windows CMD" %}

```batch
SET COLLIBRA_URL=https://<YourCollibraEnvironment>.collibra.com
SET COLLIBRA_USERNAME=<YourUsername>
SET COLLIBRA_PASSWORD=<YourPassword>
```

{% endtab %}

{% tab title="Windows PowerShell" %}

```powershell
$env:COLLIBRA_URL="https://<YourCollibraEnvironment>.collibra.com"
$env:COLLIBRA_USERNAME="<YourUsername>"
$env:COLLIBRA_PASSWORD="<YourPassword>"
```

{% endtab %}

{% tab title="Mac and Linux" %}

```bash
export COLLIBRA_URL='https://<YourCollibraEnvironment>.collibra.com'
export COLLIBRA_USERNAME='<YourUsername>'
export COLLIBRA_PASSWORD='<YourPassword>'
```

{% endtab %}
{% endtabs %}

### OAuth 2.0

{% tabs %}
{% tab title="Windows CMD" %}

```batch
SET COLLIBRA_URL=https://<YourCollibraEnvironment>.collibra.com
SET COLLIBRA_CLIENT_ID=<YourClientID>
SET COLLIBRA_CLIENT_SECRET=<YourClientSecret>
```

{% endtab %}

{% tab title="Windows PowerShell" %}

```powershell
$env:COLLIBRA_URL="https://<YourCollibraEnvironment>.collibra.com"
$env:COLLIBRA_CLIENT_ID="<YourClientID>"
$env:COLLIBRA_CLIENT_SECRET="<YourClientSecret>"
```

{% endtab %}

{% tab title="Mac and Linux" %}

```bash
export COLLIBRA_URL='https://<YourCollibraEnvironment>.collibra.com'
export COLLIBRA_CLIENT_ID='<YourClientID>'
export COLLIBRA_CLIENT_SECRET='<YourClientSecret>'
```

{% endtab %}
{% endtabs %}

Optionally, set `COLLIBRA_REDIRECT_URI` to specify the redirect URI registered in your Collibra OAuth application.

The environment variables set this way are temporary and apply only to the current terminal session. To make them permanent, add the same lines to your shell configuration file, such as `~/.bashrc`, `~/.zshrc`, or `~/.bash_profile`, then restart your terminal.

If your organization uses a proxy, add the `https_proxy` variable alongside the others, for example:

```bash
export https_proxy='https://<YourProxyHost>:<Port>'
```

## Log in with OAuth

If you configured the CLI to use OAuth 2.0, run the following command to authenticate:

* Windows: `.\collibra login`
* Linux or Mac: `./collibra login`

Your browser opens. Sign in to your Collibra environment to complete authentication. Your token is stored securely and refreshed automatically for all subsequent CLI commands.

* Your token is stored securely, using the OS credential store on Mac and Linux, and DPAPI on Windows.
* Your token is valid for up to one hour of activity. After one hour of inactivity, run `collibra login` again to re-authenticate.

## Verify the setup

Run the following command to confirm that the CLI is configured correctly and can reach your environment:

* Windows: `.\collibra info`
* Linux or Mac: `./collibra info`

If the setup is successful, the CLI returns information about your Collibra environment.

## General usage

The CLI is organized into command groups based on the Collibra feature area. You run commands in the following format:

```bash
./collibra <command-group> <action> [flags]
```

Use the `--help` flag at any level to see the available commands and flags:

```bash
./collibra --help
./collibra <command-group> --help
./collibra <command-group> <action> --help
```

The following command groups are available:

* `ai-gov`: [Register and manage AI model versions](https://productresources.collibra.com/docs/collibra/latest/Content/AICommandCenter/co_aicc-cli-tool.htm) in Collibra.
* `data-contract`: [Create and manage data contracts](https://productresources.collibra.com/docs/collibra/latest/Content/DataProducts/ta_create-data-contract-api-cli.htm) and their manifest files.