> ## Documentation Index
> Fetch the complete documentation index at: https://docs.controlplane.com/llms.txt
> Use this file to discover all available pages before exploring further.

# identity

> cpln identity — Manage identities within a GVC to grant workloads access to cloud resources and secrets.

Manage identities within a global virtual cloud

For a detailed overview, please visit the [identity's](/reference/identity) reference page.

```none theme={null}
cpln identity [SUBCOMMAND]
```

```text theme={null}
Commands:
  cpln identity access-report <ref>  Show the access report for the referenced identity
  cpln identity audit [ref]          Retrieve audit trail events for the referenced identity
  cpln identity create               Create a new identity
  cpln identity delete <ref...>      Delete one or more referenced identities
  cpln identity edit <ref>           Edit the referenced identity, as YAML, within an editor
  cpln identity eventlog <ref>       Show the event log of the referenced identity  [aliases: log]
  cpln identity get [ref...]         Retrieve one or more referenced identities
  cpln identity patch <ref>          Update the referenced identity's metadata using an input file
  cpln identity permissions          Show the grantable permissions for an identity object type
  cpln identity query                Find all the identities based on the given query
  cpln identity tag <ref...>         Manage the tags belonging to one or more referenced identities
  cpln identity update <ref>         Update properties of the referenced identity

Options:
  --help  Show help  [boolean]
```

***

#### identity access-report

Show the access report for the referenced identity

**Usage**

```none theme={null}
cpln identity access-report <ref> [OPTIONS]
```

<Accordion title="Reference">
  ```text theme={null}
  Positionals:
    ref  The resource reference. Usually it is the name of the resource.  [required]

  Context options:
    --profile  Override the profile. The default profile can be set using the `cpln profile set-default` command or by setting the CPLN_PROFILE environment variable
    --org      Override the organization. The default organization can be set in your profile by using the `cpln profile update` command
    --gvc      Override the global virtual cloud. The default global virtual cloud can be set in your profile by using the `cpln profile update` command

  Format options:
    --output, -o  Set the output format  [choices: "text", "json", "yaml", "json-slim", "yaml-slim", "tf", "crd", "names"]
    --color       Colorize the output  [boolean] [default: true]
    --ts          Timestamp format if the output format is text (e.g., --output=text)  [choices: "iso", "local", "age"]
    --max         Maximum number of records to show. A value less than 1 will return all records.  [number] [default: 50]

  Request options:
    --token         Override the authorization token
    --endpoint      Override the API URL
    --insecure, -k  Ignore TLS errors  [boolean]

  Debug options:
    --verbose, -v  Enable verbose output to stderr  [boolean] [default: false]
    --debug, -d    Show all HTTP communications  [boolean] [default: false]

  Options:
    --help  Show help  [boolean]
  ```

  [Common Options Reference](/cli-reference/using-cli/common-options)
</Accordion>

<Accordion title="Example">
  <CodeGroup>
    ```bash Command theme={null}
    cpln identity access-report demo-identity --org demo-cpln-organization --gvc demo-gvc-identity
    ```

    ```text Output theme={null}
    +-----------+--------------------------------------------------------+--------+
    |PERMISSION |PRINCIPAL                                               |GRANTED |
    |-----------|--------------------------------------------------------|--------|
    |create     |/org/demo-cpln-organization/group/superusers            |manage  |
    |create     |/org/demo-cpln-organization/serviceaccount/controlplane |manage  |
    |delete     |/org/demo-cpln-organization/group/superusers            |manage  |
    |delete     |/org/demo-cpln-organization/serviceaccount/controlplane |manage  |
    |edit       |/org/demo-cpln-organization/group/superusers            |manage  |
    |edit       |/org/demo-cpln-organization/serviceaccount/controlplane |manage  |
    |manage     |/org/demo-cpln-organization/group/superusers            |manage  |
    |manage     |/org/demo-cpln-organization/serviceaccount/controlplane |manage  |
    |use        |/org/demo-cpln-organization/group/superusers            |manage  |
    |use        |/org/demo-cpln-organization/serviceaccount/controlplane |manage  |
    |view       |/org/demo-cpln-organization/group/superusers            |manage  |
    |view       |/org/demo-cpln-organization/serviceaccount/controlplane |manage  |
    |view       |/org/demo-cpln-organization/group/viewers               |view    |
    +-----------+--------------------------------------------------------+--------+
    ```
  </CodeGroup>
</Accordion>

***

#### identity audit

Retrieve audit trail events for the referenced identity

**Usage**

```none theme={null}
cpln identity audit [ref] [OPTIONS]
```

<Accordion title="Reference">
  ```text theme={null}
  Positionals:
    ref  The resource reference. Usually it is the name of the resource.

  Command options:
    --subject  Filter by subject (serviceaccount name or user email)  [string]
    --context  Audit context name (the 'cpln' context displays Control Plane actions)  [string] [default: "cpln"]
    --since    Relative lookback window from now (e.g., 1h, 24h, 7d). Mutually exclusive with --from/--to  [string] [default: "7d"]
    --from     Start time for audit events (ISO 8601 format or relative duration, e.g., 2025-10-23T07:00:00Z, 7d, 1h). Cannot be used with --since  [string]
    --to       End time for audit events (ISO 8601 format or relative duration, e.g., 2025-10-23T07:00:00Z, 1d, 30m)  [string]

  Context options:
    --profile  Override the profile. The default profile can be set using the `cpln profile set-default` command or by setting the CPLN_PROFILE environment variable
    --org      Override the organization. The default organization can be set in your profile by using the `cpln profile update` command
    --gvc      Override the global virtual cloud. The default global virtual cloud can be set in your profile by using the `cpln profile update` command

  Format options:
    --output, -o  Set the output format  [choices: "text", "json", "yaml", "json-slim", "yaml-slim", "tf", "crd", "names"]
    --color       Colorize the output  [boolean] [default: true]
    --ts          Timestamp format if the output format is text (e.g., --output=text)  [choices: "iso", "local", "age"]
    --max         Maximum number of records to show. A value less than 1 will return all records.  [number] [default: 50]

  Request options:
    --token         Override the authorization token
    --endpoint      Override the API URL
    --insecure, -k  Ignore TLS errors  [boolean]

  Debug options:
    --verbose, -v  Enable verbose output to stderr  [boolean] [default: false]
    --debug, -d    Show all HTTP communications  [boolean] [default: false]

  Options:
    --help  Show help  [boolean]
  ```

  [Common Options Reference](/cli-reference/using-cli/common-options)
</Accordion>

***

#### identity create

Create a new identity

**Usage**

```none theme={null}
cpln identity create --name IDENTITY_NAME [OPTIONS]
```

<Accordion title="Reference">
  ```text theme={null}
  Command options:
    --name                 Name of the new identity  [required]
    --description, --desc  Optional description, defaults to the name if not set
    --tag                  Attach tags (e.g., --tag drink=water)

  Context options:
    --profile  Override the profile. The default profile can be set using the `cpln profile set-default` command or by setting the CPLN_PROFILE environment variable
    --org      Override the organization. The default organization can be set in your profile by using the `cpln profile update` command
    --gvc      Override the global virtual cloud. The default global virtual cloud can be set in your profile by using the `cpln profile update` command

  Format options:
    --output, -o  Set the output format  [choices: "text", "json", "yaml", "json-slim", "yaml-slim", "tf", "crd", "names"]
    --color       Colorize the output  [boolean] [default: true]
    --ts          Timestamp format if the output format is text (e.g., --output=text)  [choices: "iso", "local", "age"]
    --max         Maximum number of records to show. A value less than 1 will return all records.  [number] [default: 50]

  Request options:
    --token         Override the authorization token
    --endpoint      Override the API URL
    --insecure, -k  Ignore TLS errors  [boolean]

  Debug options:
    --verbose, -v  Enable verbose output to stderr  [boolean] [default: false]
    --debug, -d    Show all HTTP communications  [boolean] [default: false]

  Options:
    --help  Show help  [boolean]
  ```

  [Common Options Reference](/cli-reference/using-cli/common-options)
</Accordion>

<Accordion title="Example">
  <CodeGroup>
    ```bash Command theme={null}
    cpln identity create --name demo-identity --desc demo-identity --tag drink=water --org demo-cpln-organization --gvc demo-gvc-identity
    ```

    ```text Output theme={null}
    +--------------+--------------+------------------+-------------------------------+--------+----------+--------------+
    |NAME          |DESCRIPTION   |GVC               |LOCAL NAME                     |CREATED |PROVIDERS |TAGS          |
    |--------------|--------------|------------------|-------------------------------|--------|----------|--------------|
    |demo-identity |demo-identity |demo-gvc-identity |cpln-demo-cpln-organi-ne34r8ky |Now     |          |drink="water" |
    +--------------+--------------+------------------+-------------------------------+--------+----------+--------------+
    ```
  </CodeGroup>
</Accordion>

***

#### identity delete

Delete one or more referenced identities

**Usage**

```none theme={null}
cpln identity delete <ref...> [OPTIONS]
```

<Accordion title="Reference">
  ```text theme={null}
  Positionals:
    ref  One or more resource references. Usually it is the name of the resource.  [array] [required] [default: []]

  Context options:
    --profile  Override the profile. The default profile can be set using the `cpln profile set-default` command or by setting the CPLN_PROFILE environment variable
    --org      Override the organization. The default organization can be set in your profile by using the `cpln profile update` command
    --gvc      Override the global virtual cloud. The default global virtual cloud can be set in your profile by using the `cpln profile update` command

  Format options:
    --output, -o  Set the output format  [choices: "text", "json", "yaml", "json-slim", "yaml-slim", "tf", "crd", "names"]
    --color       Colorize the output  [boolean] [default: true]
    --ts          Timestamp format if the output format is text (e.g., --output=text)  [choices: "iso", "local", "age"]
    --max         Maximum number of records to show. A value less than 1 will return all records.  [number] [default: 50]

  Request options:
    --token         Override the authorization token
    --endpoint      Override the API URL
    --insecure, -k  Ignore TLS errors  [boolean]

  Debug options:
    --verbose, -v  Enable verbose output to stderr  [boolean] [default: false]
    --debug, -d    Show all HTTP communications  [boolean] [default: false]

  Options:
    --help  Show help  [boolean]
  ```

  [Common Options Reference](/cli-reference/using-cli/common-options)
</Accordion>

<Accordion title="Example">
  <CodeGroup>
    ```bash Command theme={null}
    cpln identity delete demo-identity --org demo-cpln-organization --gvc demo-gvc-identity
    ```

    ```text Output theme={null}
    If the delete was successful, a new command prompt will be shown.
    ```
  </CodeGroup>
</Accordion>

***

#### identity edit

Edit the referenced identity, as YAML, within an editor

**Usage**

```none theme={null}
cpln identity edit <ref> [OPTIONS]
```

<Note>
  The default editor can be set by using the EDITOR environment variable.
</Note>

<Accordion title="Reference">
  ```text theme={null}
  Positionals:
    ref  The resource reference. Usually it is the name of the resource.  [required]

  Command options:
    --replace, -r  Replace instead of patch/merge  [boolean] [default: false]

  Context options:
    --profile  Override the profile. The default profile can be set using the `cpln profile set-default` command or by setting the CPLN_PROFILE environment variable
    --org      Override the organization. The default organization can be set in your profile by using the `cpln profile update` command
    --gvc      Override the global virtual cloud. The default global virtual cloud can be set in your profile by using the `cpln profile update` command

  Format options:
    --output, -o  Set the output format  [choices: "text", "json", "yaml", "json-slim", "yaml-slim", "tf", "crd", "names"]
    --color       Colorize the output  [boolean] [default: true]
    --ts          Timestamp format if the output format is text (e.g., --output=text)  [choices: "iso", "local", "age"]
    --max         Maximum number of records to show. A value less than 1 will return all records.  [number] [default: 50]

  Request options:
    --token         Override the authorization token
    --endpoint      Override the API URL
    --insecure, -k  Ignore TLS errors  [boolean]

  Debug options:
    --verbose, -v  Enable verbose output to stderr  [boolean] [default: false]
    --debug, -d    Show all HTTP communications  [boolean] [default: false]

  Options:
    --help  Show help  [boolean]
  ```

  [Common Options Reference](/cli-reference/using-cli/common-options)
</Accordion>

<Accordion title="Example">
  <CodeGroup>
    ```bash Command theme={null}
    cpln identity edit demo-identity --org demo-cpln-organization --gvc demo-gvc-identity
    ```

    ```text Output theme={null}
    Your default editor will be launched.

    Once any modifications are saved, the updates will be sent to the API.
    ```
  </CodeGroup>
</Accordion>

***

#### identity eventlog

Show the event log of the referenced identity

**Usage**

```none theme={null}
cpln identity eventlog <ref> [OPTIONS]
```

<Accordion title="Reference">
  ```text theme={null}
  Positionals:
    ref  The resource reference. Usually it is the name of the resource.  [required]

  Context options:
    --profile  Override the profile. The default profile can be set using the `cpln profile set-default` command or by setting the CPLN_PROFILE environment variable
    --org      Override the organization. The default organization can be set in your profile by using the `cpln profile update` command
    --gvc      Override the global virtual cloud. The default global virtual cloud can be set in your profile by using the `cpln profile update` command

  Format options:
    --output, -o  Set the output format  [choices: "text", "json", "yaml", "json-slim", "yaml-slim", "tf", "crd", "names"]
    --color       Colorize the output  [boolean] [default: true]
    --ts          Timestamp format if the output format is text (e.g., --output=text)  [choices: "iso", "local", "age"]
    --max         Maximum number of records to show. A value less than 1 will return all records.  [number] [default: 50]

  Request options:
    --token         Override the authorization token
    --endpoint      Override the API URL
    --insecure, -k  Ignore TLS errors  [boolean]

  Debug options:
    --verbose, -v  Enable verbose output to stderr  [boolean] [default: false]
    --debug, -d    Show all HTTP communications  [boolean] [default: false]

  Options:
    --help  Show help  [boolean]
  ```

  [Common Options Reference](/cli-reference/using-cli/common-options)
</Accordion>

<Accordion title="Example">
  <CodeGroup>
    ```bash Command theme={null}
    cpln identity eventlog demo-identity --org demo-cpln-organization --gvc demo-gvc-identity
    ```

    ```text Output theme={null}
    The event log for the referenced identity will be shown.
    ```
  </CodeGroup>
</Accordion>

***

#### identity get

Retrieve one or more referenced identities

**Usage**

```none theme={null}
cpln identity get [ref...] [OPTIONS]
```

<Note>
  An empty reference will return all references
</Note>

<Accordion title="Reference">
  ```text theme={null}
  Positionals:
    ref  One or more resource references. Usually it is the name of the resource.  [array] [default: []]

  Context options:
    --profile  Override the profile. The default profile can be set using the `cpln profile set-default` command or by setting the CPLN_PROFILE environment variable
    --org      Override the organization. The default organization can be set in your profile by using the `cpln profile update` command
    --gvc      Override the global virtual cloud. The default global virtual cloud can be set in your profile by using the `cpln profile update` command

  Format options:
    --output, -o  Set the output format  [choices: "text", "json", "yaml", "json-slim", "yaml-slim", "tf", "crd", "names"]
    --color       Colorize the output  [boolean] [default: true]
    --ts          Timestamp format if the output format is text (e.g., --output=text)  [choices: "iso", "local", "age"]
    --max         Maximum number of records to show. A value less than 1 will return all records.  [number] [default: 50]

  Request options:
    --token         Override the authorization token
    --endpoint      Override the API URL
    --insecure, -k  Ignore TLS errors  [boolean]

  Debug options:
    --verbose, -v  Enable verbose output to stderr  [boolean] [default: false]
    --debug, -d    Show all HTTP communications  [boolean] [default: false]

  Command options:
    --all-gvcs  Show identities from all gvcs in the org  [boolean]

  Options:
    --help  Show help  [boolean]
  ```

  [Common Options Reference](/cli-reference/using-cli/common-options)
</Accordion>

<Accordion title="Example">
  * Get all identities

  <CodeGroup>
    ```bash Command theme={null}
    cpln identity get --org demo-cpln-organization --gvc demo-gvc-identity
    ```

    ```text Output theme={null}
    +--------------------+--------------------+------------------+-------------------------------+--------------+----------+--------------+
    |NAME                |DESCRIPTION         |GVC               |LOCAL NAME                     |CREATED       |PROVIDERS |TAGS          |
    |--------------------|--------------------|------------------|-------------------------------|--------------|----------|--------------|
    |demo-identity       |demo-identity       |demo-gvc-identity |cpln-demo-cpln-organi-ne34r8ky |5 minutes ago |          |drink="water" |
    |demo-identity-get-2 |demo-identity-get-2 |demo-gvc-identity |cpln-demo-cpln-organi-zsj2562k |Now           |          |              |
    |demo-identity-get-1 |demo-identity-get-1 |demo-gvc-identity |cpln-demo-cpln-organi-7bnc9t3m |Now           |          |              |
    +--------------------+--------------------+------------------+-------------------------------+--------------+----------+--------------+
    ```
  </CodeGroup>

  * Get one identity

  <CodeGroup>
    ```bash Command theme={null}
    cpln identity get demo-identity-get-1 --org demo-cpln-organization --gvc demo-gvc-identity
    ```

    ```text Output theme={null}
    +--------------------+--------------------+------------------+-------------------------------+--------+----------+-----+
    |NAME                |DESCRIPTION         |GVC               |LOCAL NAME                     |CREATED |PROVIDERS |TAGS |
    |--------------------|--------------------|------------------|-------------------------------|--------|----------|-----|
    |demo-identity-get-1 |demo-identity-get-1 |demo-gvc-identity |cpln-demo-cpln-organi-7bnc9t3m |Now     |          |     |
    +--------------------+--------------------+------------------+-------------------------------+--------+----------+-----+
    ```
  </CodeGroup>

  * Get multiple identities

  <CodeGroup>
    ```bash Command theme={null}
    cpln identity get demo-identity-get-1 demo-identity-get-2 --org demo-cpln-organization --gvc demo-gvc-identity
    ```

    ```text Output theme={null}
    +--------------------+--------------------+------------------+-------------------------------+--------+----------+-----+
    |NAME                |DESCRIPTION         |GVC               |LOCAL NAME                     |CREATED |PROVIDERS |TAGS |
    |--------------------|--------------------|------------------|-------------------------------|--------|----------|-----|
    |demo-identity-get-1 |demo-identity-get-1 |demo-gvc-identity |cpln-demo-cpln-organi-7bnc9t3m |Now     |          |     |
    |demo-identity-get-2 |demo-identity-get-2 |demo-gvc-identity |cpln-demo-cpln-organi-zsj2562k |Now     |          |     |
    +--------------------+--------------------+------------------+-------------------------------+--------+----------+-----+
    ```
  </CodeGroup>
</Accordion>

***

#### identity patch

Update the referenced identity's metadata using an input file

**Usage**

```none theme={null}
cpln identity patch <ref> --file FILE_NAME [OPTIONS]
```

<Note>
  Running this command with the option **`--file -`** sets the input to stdin. The input is required to be a valid JSON or YAML string (e.g., `{"description": "My new description"}` or `description: My new description`). To complete the update, press Control-D (or Control-Z if you are using Windows).
</Note>

<Accordion title="Reference">
  ```text theme={null}
  Positionals:
    ref  The resource reference. Usually it is the name of the resource.  [required]

  Command options:
    --file, -f  File to load the patch from. Use `--file -` to enable input from stdin.  [required]

  Context options:
    --profile  Override the profile. The default profile can be set using the `cpln profile set-default` command or by setting the CPLN_PROFILE environment variable
    --org      Override the organization. The default organization can be set in your profile by using the `cpln profile update` command
    --gvc      Override the global virtual cloud. The default global virtual cloud can be set in your profile by using the `cpln profile update` command

  Format options:
    --output, -o  Set the output format  [choices: "text", "json", "yaml", "json-slim", "yaml-slim", "tf", "crd", "names"]
    --color       Colorize the output  [boolean] [default: true]
    --ts          Timestamp format if the output format is text (e.g., --output=text)  [choices: "iso", "local", "age"]
    --max         Maximum number of records to show. A value less than 1 will return all records.  [number] [default: 50]

  Request options:
    --token         Override the authorization token
    --endpoint      Override the API URL
    --insecure, -k  Ignore TLS errors  [boolean]

  Debug options:
    --verbose, -v  Enable verbose output to stderr  [boolean] [default: false]
    --debug, -d    Show all HTTP communications  [boolean] [default: false]

  Options:
    --help  Show help  [boolean]
  ```

  [Common Options Reference](/cli-reference/using-cli/common-options)
</Accordion>

<Accordion title="Example">
  <CodeGroup>
    ```bash Command theme={null}
    cpln identity patch demo-identity --file update.json --org demo-cpln-organization --gvc demo-gvc-identity
    ```

    ```text Output theme={null}
    The changes within the JSON file will be performed against the referenced identity.
    ```
  </CodeGroup>
</Accordion>

***

#### identity permissions

Show the grantable permissions for an identity object type

**Usage**

```none theme={null}
cpln identity permissions [OPTIONS]
```

<Accordion title="Reference">
  ```text theme={null}
  Context options:
    --profile  Override the profile. The default profile can be set using the `cpln profile set-default` command or by setting the CPLN_PROFILE environment variable
    --org      Override the organization. The default organization can be set in your profile by using the `cpln profile update` command
    --gvc      Override the global virtual cloud. The default global virtual cloud can be set in your profile by using the `cpln profile update` command

  Format options:
    --output, -o  Set the output format  [choices: "text", "json", "yaml", "json-slim", "yaml-slim", "tf", "crd", "names"]
    --color       Colorize the output  [boolean] [default: true]
    --ts          Timestamp format if the output format is text (e.g., --output=text)  [choices: "iso", "local", "age"]
    --max         Maximum number of records to show. A value less than 1 will return all records.  [number] [default: 50]

  Request options:
    --token         Override the authorization token
    --endpoint      Override the API URL
    --insecure, -k  Ignore TLS errors  [boolean]

  Debug options:
    --verbose, -v  Enable verbose output to stderr  [boolean] [default: false]
    --debug, -d    Show all HTTP communications  [boolean] [default: false]

  Options:
    --help  Show help  [boolean]
  ```

  [Common Options Reference](/cli-reference/using-cli/common-options)
</Accordion>

<Accordion title="Example">
  <CodeGroup>
    ```bash Command theme={null}
    cpln identity permissions --org demo-cpln-organization --gvc demo-gvc-identity
    ```

    ```text Output theme={null}
    +-------+-----------------------------------------+----------------------------------------+
    |NAME   |DESCRIPTION                              |IMPLIES                                 |
    |-------|-----------------------------------------|----------------------------------------|
    |create |Create new identities                    |                                        |
    |delete |Delete existing identities               |                                        |
    |edit   |Modify existing identities               |view                                    |
    |manage |Full access                              |create, delete, edit, manage, use, view |
    |use    |Refer to this identity from other ent... |view                                    |
    |view   |Read-only access                         |                                        |
    +-------+-----------------------------------------+----------------------------------------+
    ```
  </CodeGroup>
</Accordion>

***

#### identity query

Find all the identities based on the given query

**Usage**

```none theme={null}
cpln identity query QUERY_OPTIONS [OPTIONS]
```

<Accordion title="Reference">
  ```text theme={null}
  Query options:
    --match             Query filter type  [choices: "all", "none", "any"] [default: "all"]
    --property, --prop  Property to query
    --tag               Tag to query
    --rel               Relation to query

  Context options:
    --profile  Override the profile. The default profile can be set using the `cpln profile set-default` command or by setting the CPLN_PROFILE environment variable
    --org      Override the organization. The default organization can be set in your profile by using the `cpln profile update` command
    --gvc      Override the global virtual cloud. The default global virtual cloud can be set in your profile by using the `cpln profile update` command

  Format options:
    --output, -o  Set the output format  [choices: "text", "json", "yaml", "json-slim", "yaml-slim", "tf", "crd", "names"]
    --color       Colorize the output  [boolean] [default: true]
    --ts          Timestamp format if the output format is text (e.g., --output=text)  [choices: "iso", "local", "age"]
    --max         Maximum number of records to show. A value less than 1 will return all records.  [number] [default: 50]

  Request options:
    --token         Override the authorization token
    --endpoint      Override the API URL
    --insecure, -k  Ignore TLS errors  [boolean]

  Debug options:
    --verbose, -v  Enable verbose output to stderr  [boolean] [default: false]
    --debug, -d    Show all HTTP communications  [boolean] [default: false]

  Options:
    --help  Show help  [boolean]
  ```

  [Common Options Reference](/cli-reference/using-cli/common-options)
</Accordion>

<Accordion title="Example">
  <Note>
    Use the `--match` option to display **all**, **none**, or **any** of the results based on a given property or tag
  </Note>

  * Search for an identity based on the name property

  <CodeGroup>
    ```bash Command theme={null}
    cpln identity query --match any --prop name=demo-identity --org demo-cpln-organization --gvc demo-gvc-identity
    ```

    ```text Output theme={null}
    +--------------------+--------------------+------------------+-------------------------------+--------------+----------+--------------+
    |NAME                |DESCRIPTION         |GVC               |LOCAL NAME                     |CREATED       |PROVIDERS |TAGS          |
    |--------------------|--------------------|------------------|-------------------------------|--------------|----------|--------------|
    |demo-identity       |demo-identity       |demo-gvc-identity |cpln-demo-cpln-organi-ne34r8ky |5 minutes ago |          |drink="water" |
    |demo-identity-get-2 |demo-identity-get-2 |demo-gvc-identity |cpln-demo-cpln-organi-zsj2562k |Now           |          |              |
    |demo-identity-get-1 |demo-identity-get-1 |demo-gvc-identity |cpln-demo-cpln-organi-7bnc9t3m |Now           |          |              |
    +--------------------+--------------------+------------------+-------------------------------+--------------+----------+--------------+
    ```
  </CodeGroup>

  * Search for an identity based on the description property

  <CodeGroup>
    ```bash Command theme={null}
    cpln identity query --match any --prop description="demo-identity" --org demo-cpln-organization --gvc demo-gvc-identity
    ```

    ```text Output theme={null}
    +--------------------+--------------------+------------------+-------------------------------+--------------+----------+--------------+
    |NAME                |DESCRIPTION         |GVC               |LOCAL NAME                     |CREATED       |PROVIDERS |TAGS          |
    |--------------------|--------------------|------------------|-------------------------------|--------------|----------|--------------|
    |demo-identity       |demo-identity       |demo-gvc-identity |cpln-demo-cpln-organi-ne34r8ky |5 minutes ago |          |drink="water" |
    |demo-identity-get-2 |demo-identity-get-2 |demo-gvc-identity |cpln-demo-cpln-organi-zsj2562k |Now           |          |              |
    |demo-identity-get-1 |demo-identity-get-1 |demo-gvc-identity |cpln-demo-cpln-organi-7bnc9t3m |Now           |          |              |
    +--------------------+--------------------+------------------+-------------------------------+--------------+----------+--------------+
    ```
  </CodeGroup>

  * Search for an identity based on a tag

  <CodeGroup>
    ```bash Command theme={null}
    cpln identity query --match any --tag drink=water --org demo-cpln-organization --gvc demo-gvc-identity
    ```

    ```text Output theme={null}
    +--------------------+--------------------+------------------+-------------------------------+--------------+----------+--------------+
    |NAME                |DESCRIPTION         |GVC               |LOCAL NAME                     |CREATED       |PROVIDERS |TAGS          |
    |--------------------|--------------------|------------------|-------------------------------|--------------|----------|--------------|
    |demo-identity       |demo-identity       |demo-gvc-identity |cpln-demo-cpln-organi-ne34r8ky |5 minutes ago |          |drink="water" |
    |demo-identity-get-2 |demo-identity-get-2 |demo-gvc-identity |cpln-demo-cpln-organi-zsj2562k |Now           |          |              |
    |demo-identity-get-1 |demo-identity-get-1 |demo-gvc-identity |cpln-demo-cpln-organi-7bnc9t3m |Now           |          |              |
    +--------------------+--------------------+------------------+-------------------------------+--------------+----------+--------------+
    ```
  </CodeGroup>

  * Search for an identity based on a property and tag

  <CodeGroup>
    ```bash Command theme={null}
    cpln identity query --match any --prop description="demo-identity" --tag drink=water --org demo-cpln-organization --gvc demo-gvc-identity
    ```

    ```text Output theme={null}
    +--------------------+--------------------+------------------+-------------------------------+--------------+----------+--------------+
    |NAME                |DESCRIPTION         |GVC               |LOCAL NAME                     |CREATED       |PROVIDERS |TAGS          |
    |--------------------|--------------------|------------------|-------------------------------|--------------|----------|--------------|
    |demo-identity       |demo-identity       |demo-gvc-identity |cpln-demo-cpln-organi-ne34r8ky |5 minutes ago |          |drink="water" |
    |demo-identity-get-2 |demo-identity-get-2 |demo-gvc-identity |cpln-demo-cpln-organi-zsj2562k |Now           |          |              |
    |demo-identity-get-1 |demo-identity-get-1 |demo-gvc-identity |cpln-demo-cpln-organi-7bnc9t3m |Now           |          |              |
    +--------------------+--------------------+------------------+-------------------------------+--------------+----------+--------------+
    ```
  </CodeGroup>
</Accordion>

***

#### identity tag

Manage the tags belonging to one or more referenced identities

**Usage**

```none theme={null}
cpln identity tag <ref...> --tag KEY=VALUE [OPTIONS]
```

<Note>
  Built-in tags, which begin with cpln/\*, can't be modified.
</Note>

<Accordion title="Reference">
  ```text theme={null}
  Positionals:
    ref  One or more resource references. Usually it is the name of the resource.  [array] [required] [default: []]

  Command options:
    --tag         Attach tags (e.g., --tag drink=water)
    --remove-tag  Remove tags (e.g., --remove-tag tagname)

  Context options:
    --profile  Override the profile. The default profile can be set using the `cpln profile set-default` command or by setting the CPLN_PROFILE environment variable
    --org      Override the organization. The default organization can be set in your profile by using the `cpln profile update` command
    --gvc      Override the global virtual cloud. The default global virtual cloud can be set in your profile by using the `cpln profile update` command

  Format options:
    --output, -o  Set the output format  [choices: "text", "json", "yaml", "json-slim", "yaml-slim", "tf", "crd", "names"]
    --color       Colorize the output  [boolean] [default: true]
    --ts          Timestamp format if the output format is text (e.g., --output=text)  [choices: "iso", "local", "age"]
    --max         Maximum number of records to show. A value less than 1 will return all records.  [number] [default: 50]

  Request options:
    --token         Override the authorization token
    --endpoint      Override the API URL
    --insecure, -k  Ignore TLS errors  [boolean]

  Debug options:
    --verbose, -v  Enable verbose output to stderr  [boolean] [default: false]
    --debug, -d    Show all HTTP communications  [boolean] [default: false]

  Options:
    --help  Show help  [boolean]
  ```

  [Common Options Reference](/cli-reference/using-cli/common-options)
</Accordion>

<Accordion title="Example">
  * Add a tag

  <CodeGroup>
    ```bash Command theme={null}
    cpln identity tag demo-identity --tag drink=water --org demo-cpln-organization --gvc demo-gvc-identity
    ```

    ```text Output theme={null}
    +--------------+--------------+------------------+-------------------------------+--------------+----------+--------------+
    |NAME          |DESCRIPTION   |GVC               |LOCAL NAME                     |CREATED       |PROVIDERS |TAGS          |
    |--------------|--------------|------------------|-------------------------------|--------------|----------|--------------|
    |demo-identity |demo-identity |demo-gvc-identity |cpln-demo-cpln-organi-ne34r8ky |5 minutes ago |          |drink="water" |
    +--------------+--------------+------------------+-------------------------------+--------------+----------+--------------+
    ```
  </CodeGroup>

  * Update same tag (after running the example above)

  <CodeGroup>
    ```bash Command theme={null}
    cpln identity tag demo-identity --tag drink=coffee --org demo-cpln-organization --gvc demo-gvc-identity
    ```

    ```text Output theme={null}
    +--------------+--------------+------------------+-------------------------------+--------------+----------+---------------+
    |NAME          |DESCRIPTION   |GVC               |LOCAL NAME                     |CREATED       |PROVIDERS |TAGS           |
    |--------------|--------------|------------------|-------------------------------|--------------|----------|---------------|
    |demo-identity |demo-identity |demo-gvc-identity |cpln-demo-cpln-organi-ne34r8ky |5 minutes ago |          |drink="coffee" |
    +--------------+--------------+------------------+-------------------------------+--------------+----------+---------------+
    ```
  </CodeGroup>

  * Remove tag (after running the example above)

  <CodeGroup>
    ```bash Command theme={null}
    cpln identity tag demo-identity --remove drink --org demo-cpln-organization --gvc demo-gvc-identity
    ```

    ```text Output theme={null}
    +--------------+--------------+------------------+-------------------------------+--------------+----------+-----+
    |NAME          |DESCRIPTION   |GVC               |LOCAL NAME                     |CREATED       |PROVIDERS |TAGS |
    |--------------|--------------|------------------|-------------------------------|--------------|----------|-----|
    |demo-identity |demo-identity |demo-gvc-identity |cpln-demo-cpln-organi-ne34r8ky |5 minutes ago |          |     |
    +--------------+--------------+------------------+-------------------------------+--------------+----------+-----+
    ```
  </CodeGroup>
</Accordion>

***

#### identity update

Update properties of the referenced identity

**Usage**

```none theme={null}
cpln identity update <ref> --set UPDATE_PROPERTY [OPTIONS]
```

<Accordion title="Reference">
  ```text theme={null}
  Positionals:
    ref  The resource reference. Usually it is the name of the resource.  [required]

  Update Properties:
    --set    Update the following properties (e.g., --set description="Updated Description"):

             description    string
             tags.<key>     string
    --unset  Unset a property (same paths as --set, e.g., --unset description)

  Context options:
    --profile  Override the profile. The default profile can be set using the `cpln profile set-default` command or by setting the CPLN_PROFILE environment variable
    --org      Override the organization. The default organization can be set in your profile by using the `cpln profile update` command
    --gvc      Override the global virtual cloud. The default global virtual cloud can be set in your profile by using the `cpln profile update` command

  Format options:
    --output, -o  Set the output format  [choices: "text", "json", "yaml", "json-slim", "yaml-slim", "tf", "crd", "names"]
    --color       Colorize the output  [boolean] [default: true]
    --ts          Timestamp format if the output format is text (e.g., --output=text)  [choices: "iso", "local", "age"]
    --max         Maximum number of records to show. A value less than 1 will return all records.  [number] [default: 50]

  Request options:
    --token         Override the authorization token
    --endpoint      Override the API URL
    --insecure, -k  Ignore TLS errors  [boolean]

  Debug options:
    --verbose, -v  Enable verbose output to stderr  [boolean] [default: false]
    --debug, -d    Show all HTTP communications  [boolean] [default: false]

  Options:
    --help  Show help  [boolean]
  ```

  [Common Options Reference](/cli-reference/using-cli/common-options)
</Accordion>

<Accordion title="Options">
  * The `--set` option allows the modification of the following identity properties:
    * `description`
      * Description of the identity
      * Type: string
    * `tags`
      * Tags (key=value) associated with the identity
      * Type: string
</Accordion>

<Accordion title="Example">
  * For the examples below, the initial identity is configured as:

  ```
  +---------------------+---------------------+------------------+-------------------------------+--------+----------+-----+
  |NAME                 |DESCRIPTION          |GVC               |LOCAL NAME                     |CREATED |PROVIDERS |TAGS |
  |---------------------|---------------------|------------------|-------------------------------|--------|----------|-----|
  |demo-identity-update |demo-identity-update |demo-gvc-identity |cpln-demo-cpln-organi-23r0tn29 |Now     |          |     |
  +---------------------+---------------------+------------------+-------------------------------+--------+----------+-----+
  ```

  * Update an identity's description

  <CodeGroup>
    ```bash Command theme={null}
    cpln identity update demo-identity-update --set description="new description" --org demo-cpln-organization --gvc demo-gvc-identity
    ```

    ```text Output theme={null}
    +---------------------+----------------+------------------+-------------------------------+--------+----------+-----+
    |NAME                 |DESCRIPTION     |GVC               |LOCAL NAME                     |CREATED |PROVIDERS |TAGS |
    |---------------------|----------------|------------------|-------------------------------|--------|----------|-----|
    |demo-identity-update |new description |demo-gvc-identity |cpln-demo-cpln-organi-23r0tn29 |Now     |          |     |
    +---------------------+----------------+------------------+-------------------------------+--------+----------+-----+
    ```
  </CodeGroup>

  * Update an identity's tag

  <CodeGroup>
    ```bash Command theme={null}
    cpln identity update demo-identity-update --set tags.demo-key=demo-value --org demo-cpln-organization --gvc demo-gvc-identity
    ```

    ```text Output theme={null}
    +---------------------+----------------+------------------+-------------------------------+--------+----------+----------------------+
    |NAME                 |DESCRIPTION     |GVC               |LOCAL NAME                     |CREATED |PROVIDERS |TAGS                  |
    |---------------------|----------------|------------------|-------------------------------|--------|----------|----------------------|
    |demo-identity-update |new description |demo-gvc-identity |cpln-demo-cpln-organi-23r0tn29 |Now     |          |demo-key="demo-value" |
    +---------------------+----------------+------------------+-------------------------------+--------+----------+----------------------+
    ```
  </CodeGroup>
</Accordion>

***