# Manage Purposes

This page details the `immuta purpose` command, its subcommands and arguments, and the workflow for creating and deleting purposes.

## Command: `immuta purpose`

This command allows you to list, save, and delete purposes in your instance of Immuta. The table below illustrates subcommands and arguments.

| Subcommands | Description                           | Argument(s)    |
| ----------- | ------------------------------------- | -------------- |
| `delete`    | Delete a purpose by name.             | `purpose name` |
| `list`      | List all purposes.                    | n/a            |
| `save`      | Create or update a purpose in Immuta. | `filepath`     |

### Options

Use these options to get more details about the `purpose` command or any of its subcommands:

* `-h`
* `--help`

```bash
Manage Purposes

Usage:
  immuta purpose [command]

Available Commands:
  delete      Delete a purpose by name
  list        List all purposes
  save        Create/update a purpose in Immuta

Flags:
  -h, --help   help for purpose

Global Flags:
      --config string    config file (default $HOME/.immutacfg.yaml)
  -p, --profile string   specifies the profile for what instance/api the cli will use (default "default")

Use "immuta purpose [command] --help" for more information about a command.
```

## Create a Purpose: `immuta purpose save`

1. Add your purpose information in a valid YAML file for the V2 API. Additional payload examples for creating purposes can [be found here](https://documentation.immuta.com/SaaS/developer-guides/api-intro/immuta-v2-api/purposes).
2. Run `immuta purpose save <filepath> [--dryRun] [--reAcknowledge]`, referencing the file you just created. The options you can specify include
   * `--reAcknowledge`: Require all users of any projects using this purpose to re-acknowledge any updated acknowledgement statements.
   * `-d` or `--dryRun`: No updates will be made.
   * `-h` or `--help`: Get more information about the command.

```yaml
name: Demo Purpose
acknowledgement: You promise not to share this data outside the project.
description: This project is only to be used for departmental data.
```

### Examples

The example below illustrates a user creating a purpose called `Demo Purpose`.

```bash
$ immuta purpose list
Re-identification Prohibited
Re-identification Prohibited.CCPA
Re-identification Prohibited.Safe Harbor Method
Use Case Outside De-identification

$ immuta purpose save test-purpose.yml
{"dryRun":false,"creating":true,"updating":false,"purposeId":8}

$ immuta purpose list
Demo Purpose
Re-identification Prohibited
Re-identification Prohibited.CCPA
Re-identification Prohibited.Safe Harbor Method
Use Case Outside De-identification
```

## Delete a Purpose: `immuta purpose delete`

**Required Immuta permission**: `GOVERNANCE`

1. Opt to list all purposes to determine which purpose you would like to delete by running `immuta purpose list`. Options you can specify include
   * `-h` or `--help`: Get more information about the command.
   * `-v` or `--verbose`: Print response as JSON.
2. Delete a purpose by running `immuta purpose delete <purpose name> [--dryRun]`, enclosing the purpose name in quotation marks. Options you can specify include
   * `-d` or `--dryRun`: No updates will be made.
   * `-h` or `--help`: Get more information about the command.

### Example

The example below illustrates a user deleting the purpose `Demo Purpose`.

```bash
$ immuta purpose list
Demo Purpose
Re-identification Prohibited
Re-identification Prohibited.CCPA
Re-identification Prohibited.Safe Harbor Method
Use Case Outside De-identification

$ immuta purpose delete "Demo Purpose"
{"dryRun":false,"deleting":["Demo Purpose"]}

$ immuta purpose list
Re-identification Prohibited
Re-identification Prohibited.CCPA
Re-identification Prohibited.Safe Harbor Method
Use Case Outside De-identification
```