# Manage Your Immuta Tenant

This page details the `immuta` command, its subcommands and arguments, and the workflow for cloning a tenant and using the Immuta API.

## Command overview: `immuta`

This command allows you to manage your Immuta tenant by creating data sources, projects, policies, and purposes. The table below illustrates the `immuta` subcommands and arguments.

| Subcommands                                                                                                                       | Description                                                                            | Argument(s)                            |
| --------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | -------------------------------------- |
| [`api`](#immuta-api)                                                                                                              | Make an authenticated Immuta API request.                                              | `endpoint`                             |
| [`clone`](#clone-your-tenant-immuta-clone)                                                                                        | Clone all data sources, projects, purposes, and policies information into files.       | `directory path`                       |
| [`completion`](https://documentation.immuta.com/saas/developer-guides/installation#3-install-tab-completions)                     | Generate shell completion scripts for Immuta CLI commands.                             | `bash`, `zsh`, `fish`, or `powershell` |
| [`configure`](https://documentation.immuta.com/saas/developer-guides/installation#id-2-configure-the-cli-with-your-immuta-tenant) | Specify an Immuta tenant URL and API key to be saved to the Immuta configuration file. | `instance url` and `Immuta API key`    |
| [`datasource`](https://documentation.immuta.com/saas/developer-guides/the-immuta-cli/datasources)                                 | Manage data sources.                                                                   | `list`, `delete`, `rename`, and `save` |
| [`policy`](https://documentation.immuta.com/saas/developer-guides/the-immuta-cli/policies)                                        | Manage Global Policies.                                                                | `list`, `delete`, `rename`, and `save` |
| [`project`](https://documentation.immuta.com/saas/developer-guides/the-immuta-cli/projects)                                       | Manage projects.                                                                       | `list`, `delete`, `rename`, and `save` |
| [`purpose`](https://documentation.immuta.com/saas/developer-guides/the-immuta-cli/purposes)                                       | Manage purposes.                                                                       | `list`, `delete`, and `save`           |
| `version`                                                                                                                         | The version of the Immuta CLI.                                                         | n/a                                    |

*To view a list of the commands available in your current Immuta CLI version, run `immuta` with no additional arguments.*

### Options

Options you can specify with the `immuta` command include

* `--config string`: Specify the configuration file name and where it will be saved. (The default is `$HOME/.immutacfg.yaml`.)
* `-h` or `--help`: Get more information about the command.
* `-p` or `--profile string`: Specify the profile for what tenant or API the CLI will use.

## Clone your tenant: `immuta clone`

**Required Immuta permission**: `GOVERNANCE`

If you have an Immuta tenant that was set up without using the API, you can use the `immuta clone` command to save all your data sources, projects, policies, and purposes as payloads:

```bash
immuta clone <outputDirPath>
```

This command will create valid V2 API YAML files for all your data sources, projects, policies, and purposes. Within these files, database passwords and user files (such as a BigQuery auth file) will be removed; instead passwords will appear as `{{EnvVar "dbPass"}}`. The CLI will then read the environment variable `dbPass` to fill in the password if you use the cloned payload to create or update a data source. File contents will appear as `{{ReadFile "<filePath>"}}`, and then the CLI will read the file at the path and replace the value when commands are run.

### Options

* `--force`: Overwrite existing output directory targets. If this flag is omitted, you will receive an error when the output directory exists and is not empty.
* `-h` or `--help`: Get details about the command.

### Limitations

* Tags for data sources and projects are not returned.
* Data sources will not have the `sources` field, so if these payloads are used in `create` commands, all possible tables will be created as data sources.

## `immuta api`

This command makes an authenticated HTTP(s) request to the Immuta API and prints the response. The default HTTP request method is `GET`, but `POST` is used if any parameters were added. You can override the method with `--method`:

```bash
immuta api <endPoint> [--method httpMethod] [--input <filePath>] [--body body] [--data key=value] [--raw-data key=value] [--header key:value] [--query key=value] [--path-param key=value] [--outputTemplate string]
```

### Options

* `-b`, `--body string`: Unmodified string to be sent as payload body.
* `-d`, `--data key=value`: Add a typed parameter in `key=value` format. The `--data` flag behaves like `--raw-data`, with type conversion based on the format of the value. Literal values, `true`, `false`, `null`, and integers are converted to appropriate JSON types. This will be sent in as the request payload.
* `--data-raw key=value`: Add a string parameter in `key=value` format. The `--data` flag behaves like `--raw-data`, with type conversion based on the format of the value. Literal values, `true`, `false`, `null`, and integers are converted to appropriate JSON types. This will be sent in as the request payload.
* `-H`, `--header key:value`: Add an HTTP request header in `key:value` format.
* `-h`, `--help`: Get details about the command.
* `--input <filepath>`: A raw request body may be passed from the outside via the file specified to use as body for the HTTP request. Pass in '-' for standard input.
* `-X`, `--method string`: The HTTP method for the request (default `GET`).
* `-P`, `--path-param key=value`: Add a string parameter in key=value format. Will replace `{key}` in the url with `value`.
* `-q`, `--query key=value`: Add a string parameter in key=value format. The key value pairs are serialized into URL query parameters.
* `-t`, `--outputTemplate string`: Format the response using a Go template. The provided Go template is rendered using the JSON data as input. For the syntax of Go templates, see [this document](https://golang.org/pkg/text/template/).

### Examples

The documentation below provides descriptions and examples of `immuta api` options.

```bash
# list tags
$ immuta api tag

# list tags use query string to filter results
$ immuta api tag -q searchText=Discovered -q limit=10

# template the response using a Go template. This will print all tags new line separated.
$ immuta api tag -q limit=10 --template \
    '{{range .}}{{.name}}{{"\n"}}{{end}}'

# Run column detection on specified table
$ immuta api dataSource/detectRemoteChanges -X PUT -d table=tableName -d schema=schemaName

# the above command is the same as
$ immuta api dataSource/detectRemoteChanges -X PUT --body '{"table": "tableName", "schema", "schemaName"}'

# set a user's current project - replace templated values in path
$ immuta api project/current/{projectId} -P projectId=1 -X POST

# the above command is the same as
$ immuta api project/current/1 -X POST
```