1 of 77

Developer Guides

The Immuta CLI

Audience: Immuta users
Content Summary: The Immuta CLI allows users to interact with their Immuta tenant using the command line to manage data sources, projects, policies, and purposes. This feature allows you to have all of your Immuta tenant information in a Git repository and use the CLI to sync your Immuta tenant with the files in your Git repository. To install the Immuta CLI, follow this installation guide.

Section Overview

You can navigate this section of documentation in two different ways: by workflow or by command.

Workflow

The navigation in the left pane is organized by major workflows you would use in Immuta. Each workflow contains relevant commands. Follow this chronological outline to find commands relevant to your workflow.

Install and Configure the Immuta CLI.
Manage Your Immuta Tenant.
Create and Manage Data Sources.
Create and Manage Global Policies.
Create and Manage Purposes.
Create and Manage Projects.

Commands

Below is a list of major commands available in the Immuta CLI. Click a command to navigate to its corresponding page that details subcommands, options, and arguments.

immuta: Interact with your Immuta tenant to create data sources, projects, policies, and purposes.
immuta api: Make an authenticated Immuta API request. This command will let you hit any endpoint in the Immuta API, including version 1 endpoints. For example, immuta api /tag will hit the v1 endpoint to list tags. This allows you to use the immuta api command instead of something like Postman or cURL to interact with the V1 API.
immuta clone: Clone all data sources, projects, purposes, and policies information into files.
immuta completion: Generate shell completion scripts.
immuta configure: Specify an Immuta tenant url and API key to be saved to the Immuta configuration file.
immuta datasource: Manage data sources.
immuta policy: Manage Global Policies.
immuta project: Manage projects.
immuta purpose: Manage purposes.

Install and Configure the CLI

Audience: Immuta users
Content Summary: This page details how to install the Immuta CLI and tab completions.

1 - Install the Immuta CLI

macOS CLI Binary Warning: When installing the macOS CLI binary, macOS displays the warning "could not verify that this app is free from malware" when the binary is run. Navigate to the Security & Privacy section in your System Preferences to allow the binary to be run.

Download the binary that corresponds to your operating system.

The latest stable binaries can be found here:

Linux x86_64 (amd64)

curl -Lo immuta https://immuta-platform-artifacts.s3.amazonaws.com/cli/latest/immuta_cli_linux_amd64 && chmod +x immuta

Linux ARMv8 (arm64)

curl -Lo immuta https://immuta-platform-artifacts.s3.amazonaws.com/cli/latest/immuta_cli_linux_arm64 && chmod +x immuta

The latest stable binaries can be found here:

Darwin x86_64 (amd64)

curl -Lo immuta https://immuta-platform-artifacts.s3.amazonaws.com/cli/latest/immuta_cli_darwin_amd64 && chmod +x immuta

Darwin ARMv8 (arm64)

curl -Lo immuta https://immuta-platform-artifacts.s3.amazonaws.com/cli/latest/immuta_cli_darwin_arm64 && chmod +x immuta

The latest stable binary can be found here: https://immuta-platform-artifacts.s3.amazonaws.com/cli/latest/immuta_cli_windows_amd64.

Download and add the binary to a directory in your system's $PATH as immuta.exe.

The SHA 256 checksum is available to verify the file at https://immuta-platform-artifacts.s3.amazonaws.com/cli/latest/immuta_cli_SHA256SUMS.

2 - Configure the CLI with Your Immuta Tenant

Run immuta configure.
Enter the URL of your Immuta tenant in the interactive prompt.
Enter your Immuta API Key in the interactive prompt:

$ immuta configure
? What is the url of the immuta instance you use?: https://your.instance.url.com/
? What is the api key of your immuta user account?:  ***************************Updated the config at /Users/user/.immutacfg.yaml

Below is the configuration file that will be saved at ~/.immutacfg.yaml:

default:

  api_key: <apiKey>

  host: https://your.immuta.url.com

3 - Install Tab Completions

To generate shell completion scripts for Immuta CLI commands, run immuta completion [bash|zsh|fish|powershell]. You can opt to specify -h or --help for instructions on installing tab completions for Bash, Zsh, Fish, and PowerShell commands and flags.

Use the tabs below for specific instructions for each of these shells.

Install bash-completion https://github.com/scop/bash-completion.
Add this to your ~/.bash_profile:
```
eval "$(immuta completion bash)"
```

Generate an _immuta completion script and save it in your $fpath:

immuta completion zsh > /usr/local/share/zsh/site-functions/_immuta

Ensure that the following is present in your ~/.zshrc:
```
autoload -U compinit
compinit -i
```

Generate an immuta.fish completion script:

immuta completion fish > ~/.config/fish/completions/immuta.fish

Run immuta completion powershell | Out-String | Invoke-Expression.
To load completions for every new session, run
```
immuta completion powershell > immuta.ps1
```
Source this immuta.ps1 from your PowerShell profile.

The exact configuration file locations might vary based on your system. Make sure to restart your shell before you test whether completions are working.

Request Payload Examples

Data Sources

Create Data Sources

Write Policies

The Immuta CLI

Audience: Immuta users
Content Summary: The Immuta CLI allows users to interact with their Immuta tenant using the command line to manage data sources, projects, policies, and purposes. This feature allows you to have all of your Immuta tenant information in a Git repository and use the CLI to sync your Immuta tenant with the files in your Git repository. To install the Immuta CLI, follow this installation guide.

Section Overview

You can navigate this section of documentation in two different ways: by workflow or by command.

Commands

Below is a list of major commands available in the Immuta CLI. Click a command to navigate to its corresponding page that details subcommands, options, and arguments.

immuta: Interact with your Immuta tenant to create data sources, projects, policies, and purposes.
immuta api: Make an authenticated Immuta API request. This command will let you hit any endpoint in the Immuta API, including version 1 endpoints. For example, immuta api /tag will hit the v1 endpoint to list tags. This allows you to use the immuta api command instead of something like Postman or cURL to interact with the V1 API.
immuta clone: Clone all data sources, projects, purposes, and policies information into files.
immuta completion: Generate shell completion scripts.
immuta configure: Specify an Immuta tenant url and API key to be saved to the Immuta configuration file.
immuta datasource: Manage data sources.
immuta policy: Manage Global Policies.
immuta project: Manage projects.
immuta purpose: Manage purposes.

Install and Configure the CLI

Audience: Immuta users
Content Summary: This page details how to install the Immuta CLI and tab completions.

1 - Install the Immuta CLI

Download the binary that corresponds to your operating system.

The latest stable binaries can be found here:

Linux x86_64 (amd64)

curl -Lo immuta https://immuta-platform-artifacts.s3.amazonaws.com/cli/latest/immuta_cli_linux_amd64 && chmod +x immuta

Linux ARMv8 (arm64)

curl -Lo immuta https://immuta-platform-artifacts.s3.amazonaws.com/cli/latest/immuta_cli_linux_arm64 && chmod +x immuta

The latest stable binaries can be found here:

Darwin x86_64 (amd64)

curl -Lo immuta https://immuta-platform-artifacts.s3.amazonaws.com/cli/latest/immuta_cli_darwin_amd64 && chmod +x immuta

Darwin ARMv8 (arm64)

curl -Lo immuta https://immuta-platform-artifacts.s3.amazonaws.com/cli/latest/immuta_cli_darwin_arm64 && chmod +x immuta

The latest stable binary can be found here: https://immuta-platform-artifacts.s3.amazonaws.com/cli/latest/immuta_cli_windows_amd64.

Download and add the binary to a directory in your system's $PATH as immuta.exe.

The SHA 256 checksum is available to verify the file at https://immuta-platform-artifacts.s3.amazonaws.com/cli/latest/immuta_cli_SHA256SUMS.

2 - Configure the CLI with Your Immuta Tenant

Run immuta configure.
Enter the URL of your Immuta tenant in the interactive prompt.
Enter your Immuta API Key in the interactive prompt:

$ immuta configure
? What is the url of the immuta instance you use?: https://your.instance.url.com/
? What is the api key of your immuta user account?:  ***************************Updated the config at /Users/user/.immutacfg.yaml

Below is the configuration file that will be saved at ~/.immutacfg.yaml:

default:

  api_key: <apiKey>

  host: https://your.immuta.url.com

3 - Install Tab Completions

Use the tabs below for specific instructions for each of these shells.

Install bash-completion https://github.com/scop/bash-completion.
Add this to your ~/.bash_profile:
```
eval "$(immuta completion bash)"
```

Generate an _immuta completion script and save it in your $fpath:

immuta completion zsh > /usr/local/share/zsh/site-functions/_immuta

Ensure that the following is present in your ~/.zshrc:
```
autoload -U compinit
compinit -i
```

Generate an immuta.fish completion script:

immuta completion fish > ~/.config/fish/completions/immuta.fish

Run immuta completion powershell | Out-String | Invoke-Expression.
To load completions for every new session, run
```
immuta completion powershell > immuta.ps1
```
Source this immuta.ps1 from your PowerShell profile.

The exact configuration file locations might vary based on your system. Make sure to restart your shell before you test whether completions are working.