# 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](/latest/developer-guides/api-intro/immuta-v2-api/purposes.md).
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
```


---

# Agent Instructions: 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:

```
GET https://documentation.immuta.com/latest/developer-guides/the-immuta-cli/purposes.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.