> ## 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.

# auditctx

> cpln auditctx — Manage audit contexts for tracking and reviewing organizational activity.

Manage audit contexts

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

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

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

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

***

#### auditctx access-report

Show the access report for the referenced audit context

**Usage**

```none theme={null}
cpln auditctx 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

  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 auditctx access-report demo-audit-context --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +-----------+--------------------------------------------------------+--------+
    |PERMISSION |PRINCIPAL                                               |GRANTED |
    |-----------|--------------------------------------------------------|--------|
    |create     |/org/demo-cpln-organization/group/superusers            |manage  |
    |create     |/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  |
    |readAudit  |/org/demo-cpln-organization/group/superusers            |manage  |
    |readAudit  |/org/demo-cpln-organization/serviceaccount/controlplane |manage  |
    |view       |/org/demo-cpln-organization/group/viewers               |view    |
    |view       |/org/demo-cpln-organization/group/superusers            |manage  |
    |view       |/org/demo-cpln-organization/serviceaccount/controlplane |manage  |
    |writeAudit |/org/demo-cpln-organization/group/superusers            |manage  |
    |writeAudit |/org/demo-cpln-organization/serviceaccount/controlplane |manage  |
    +-----------+--------------------------------------------------------+--------+
    ```
  </CodeGroup>
</Accordion>

***

#### auditctx audit

Retrieve audit trail events for the referenced audit context

**Usage**

```none theme={null}
cpln auditctx 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

  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>

***

#### auditctx clone

Create a clone of the referenced audit context; this will only duplicate its spec.

**Usage**

```none theme={null}
cpln auditctx clone <ref> --name CLONE_NAME [OPTIONS]
```

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

  Command options:
    --name         Set the name for the clone  [required]
    --description  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

  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 auditctx clone demo-audit-context --name demo-audit-context-clone --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +-------------------------+-----------------------------------------+--------+-----+
    |NAME                     |DESCRIPTION                              |ORIGIN  |TAGS |
    |-------------------------|-----------------------------------------|--------|-----|
    |demo-audit-context-clone |Clone of demo-audit-context              |default |     |
    +-------------------------+-----------------------------------------+--------+-----+
    ```
  </CodeGroup>
</Accordion>

***

#### auditctx create

Create a new audit context

**Usage**

```none theme={null}
cpln auditctx create --name NAME [OPTIONS]
```

<Accordion title="Reference">
  ```text theme={null}
  Command options:
    --name                 Name of the new audit context  [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

  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 auditctx create --name demo-audit-context --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +-------------------+-----------------------------------------+--------+-----+
    |NAME               |DESCRIPTION                              |ORIGIN  |TAGS |
    |-------------------|-----------------------------------------|--------|-----|
    |demo-audit-context |demo-audit-context                       |default |     |
    +-------------------+-----------------------------------------+--------+-----+
    ```
  </CodeGroup>
</Accordion>

***

#### auditctx edit

Edit the referenced audit context, as YAML, within an editor

**Usage**

```none theme={null}
cpln auditctx 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

  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 auditctx edit demo-audit-context --org demo-cpln-organization
    ```

    ```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>

***

#### auditctx eventlog

Show the event log of the referenced audit context

**Usage**

```none theme={null}
cpln auditctx 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

  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 auditctx eventlog demo-audit-context --org demo-cpln-organization
    ```

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

***

#### auditctx get

Retrieve one or more referenced audit contexts

**Usage**

```none theme={null}
cpln auditctx 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

  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">
  * Get all audit contexts

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

    ```text Output theme={null}
    +-------------------------+----------------------------+--------+------------+
    |NAME                     |DESCRIPTION                 |ORIGIN  |TAGS        |
    |-------------------------|----------------------------|--------|------------|
    |cpln                     |Audit of your CPLN org      |builtin |            |
    |demo-audit-context       |demo-audit-context          |default |type="demo" |
    |demo-audit-context-clone |Clone of demo-audit-context |default |            |
    +-------------------------+----------------------------+--------+------------+
    ```
  </CodeGroup>

  * Get one audit context

  <CodeGroup>
    ```bash Command theme={null}
    cpln auditctx get demo-audit-context --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +-------------------+-------------------+--------+------------+
    |NAME               |DESCRIPTION        |ORIGIN  |TAGS        |
    |-------------------|-------------------|--------|------------|
    |demo-audit-context |demo-audit-context |default |type="demo" |
    +-------------------+-------------------+--------+------------+
    ```
  </CodeGroup>

  * Get multiple audit contexts

  <CodeGroup>
    ```bash Command theme={null}
    cpln auditctx get demo-audit-context cpln --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +-------------------+-----------------------+--------+------------+
    |NAME               |DESCRIPTION            |ORIGIN  |TAGS        |
    |-------------------|-----------------------|--------|------------|
    |demo-audit-context |demo-audit-context     |default |type="demo" |
    |cpln               |Audit of your CPLN org |builtin |            |
    +-------------------+-----------------------+--------+------------+
    ```
  </CodeGroup>
</Accordion>

***

#### auditctx patch

Update the referenced audit context's metadata using an input file

**Usage**

```none theme={null}
cpln auditctx 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

  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 auditctx patch demo-audit-context --file update.json --org demo-cpln-organization
    ```

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

***

#### auditctx permissions

Show the grantable permissions for an audit context object type

**Usage**

```none theme={null}
cpln auditctx 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

  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 auditctx permissions --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +-----------+-------------------------+--------------------------------------------------+
    |NAME       |DESCRIPTION              |IMPLIES                                           |
    |-----------|-------------------------|--------------------------------------------------|
    |create     |Create new contexts      |                                                  |
    |edit       |Modify existing contexts |view                                              |
    |manage     |Full access              |create, edit, manage, readAudit, view, writeAudit |
    |readAudit  |Read from this context   |view                                              |
    |view       |Read-only view           |                                                  |
    |writeAudit |Write to this context    |view                                              |
    +-----------+-------------------------+--------------------------------------------------+
    ```
  </CodeGroup>
</Accordion>

***

#### auditctx query

Find all the audit contexts based on the given query

**Usage**

```none theme={null}
cpln auditctx 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

  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 audit context based on the name property

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

    ```text Output theme={null}
    +-------------------+-------------------+--------+------------+
    |NAME               |DESCRIPTION        |ORIGIN  |TAGS        |
    |-------------------|-------------------|--------|------------|
    |demo-audit-context |demo-audit-context |default |type="demo" |
    +-------------------+-------------------+--------+------------+
    ```
  </CodeGroup>

  * Search for an audit context based on the description property

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

    ```text Output theme={null}
    +-------------------+-------------------+--------+------------+
    |NAME               |DESCRIPTION        |ORIGIN  |TAGS        |
    |-------------------|-------------------|--------|------------|
    |demo-audit-context |demo-audit-context |default |type="demo" |
    +-------------------+-------------------+--------+------------+
    ```
  </CodeGroup>

  * Search for an audit context based on a tag

  <CodeGroup>
    ```bash Command theme={null}
    cpln auditctx query --match any --tag type=demo --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +-------------------+-------------------+--------+------------+
    |NAME               |DESCRIPTION        |ORIGIN  |TAGS        |
    |-------------------|-------------------|--------|------------|
    |demo-audit-context |demo-audit-context |default |type="demo" |
    +-------------------+-------------------+--------+------------+
    ```
  </CodeGroup>

  * Search for an audit context based on a property and tag

  <CodeGroup>
    ```bash Command theme={null}
    cpln auditctx query --match any --prop description="demo-audit-context" --tag type=demo --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +-------------------+-------------------+--------+------------+
    |NAME               |DESCRIPTION        |ORIGIN  |TAGS        |
    |-------------------|-------------------|--------|------------|
    |demo-audit-context |demo-audit-context |default |type="demo" |
    +-------------------+-------------------+--------+------------+
    ```
  </CodeGroup>
</Accordion>

***

#### auditctx tag

Manage the tags belonging to one or more referenced audit contexts

**Usage**

```none theme={null}
cpln auditctx 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

  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 auditctx tag demo-audit-context --tag drink=water --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +-------------------+-------------------+--------+--------------+
    |NAME               |DESCRIPTION        |ORIGIN  |TAGS          |
    |-------------------|-------------------|--------|--------------|
    |demo-audit-context |demo-audit-context |default |drink="water" |
    |                   |                   |        |type="demo"   |
    +-------------------+-------------------+--------+--------------+
    ```
  </CodeGroup>

  * Update same tag (after running the example above)

  <CodeGroup>
    ```bash Command theme={null}
    cpln auditctx tag demo-audit-context --tag drink=coffee --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +-------------------+-------------------+--------+---------------+
    |NAME               |DESCRIPTION        |ORIGIN  |TAGS           |
    |-------------------|-------------------|--------|---------------|
    |demo-audit-context |demo-audit-context |default |drink="coffee" |
    |                   |                   |        |type="demo"    |
    +-------------------+-------------------+--------+---------------+
    ```
  </CodeGroup>

  * Remove tag (after running the example above)

  <CodeGroup>
    ```bash Command theme={null}
    cpln auditctx tag demo-audit-context --remove drink --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +-------------------+-------------------+--------+------------+
    |NAME               |DESCRIPTION        |ORIGIN  |TAGS        |
    |-------------------|-------------------|--------|------------|
    |demo-audit-context |demo-audit-context |default |type="demo" |
    +-------------------+-------------------+--------+------------+
    ```
  </CodeGroup>
</Accordion>

***

#### auditctx update

Update properties of the referenced audit context

**Usage**

```none theme={null}
cpln auditctx 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

  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 audit context properties:
    * `description`
      * Description of the audit context
      * Type: string
    * `tags`
      * Tags (key=value) associated with the audit context
      * Type: string
</Accordion>

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

  ```text theme={null}
  +-------------------+-------------------+--------+------------+
  |NAME               |DESCRIPTION        |ORIGIN  |TAGS        |
  |-------------------|-------------------|--------|------------|
  |demo-audit-context |demo-audit-context |default |type="demo" |
  +-------------------+-------------------+--------+------------+
  ```

  * Update an audit context's description

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

    ```text Output theme={null}
    +-------------------+----------------+--------+------------+
    |NAME               |DESCRIPTION     |ORIGIN  |TAGS        |
    |-------------------|----------------|--------|------------|
    |demo-audit-context |new description |default |type="demo" |
    +-------------------+----------------+--------+------------+
    ```
  </CodeGroup>

  * Update an audit context's tag

  <CodeGroup>
    ```bash Command theme={null}
    cpln auditctx update demo-audit-context --set tags.type=updated --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +-------------------+----------------+--------+---------------+
    |NAME               |DESCRIPTION     |ORIGIN  |TAGS           |
    |-------------------|----------------|--------|---------------|
    |demo-audit-context |new description |default |type="updated" |
    +-------------------+----------------+--------+---------------+
    ```
  </CodeGroup>
</Accordion>

***