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

# group

> cpln group — Manage groups for organizing users and service accounts.

Manage groups

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

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

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

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

***

#### group access-report

Show the access report for the referenced group

**Usage**

```none theme={null}
cpln group 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 group access-report demo-group --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  |
    |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  |
    |view       |/org/demo-cpln-organization/group/viewers               |view    |
    |view       |/org/demo-cpln-organization/group/superusers            |manage  |
    |view       |/org/demo-cpln-organization/serviceaccount/controlplane |manage  |
    +-----------+--------------------------------------------------------+--------+
    ```
  </CodeGroup>
</Accordion>

***

#### group add-member

Add members to the referenced group

**Usage**

```none theme={null}
cpln group add-member <ref> --email USER_EMAIL [OPTIONS]

cpln group add-member <ref> --serviceaccount SERVICE_ACCOUNT [OPTIONS]
```

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

  Command options:
    --email           Email of user to add
    --serviceaccount  Name of the service account to add

  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 user to a group

  <CodeGroup>
    ```bash Command theme={null}
    cpln group add-member demo-group --email test-128@example.com --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +-----------+------------+--------------+-------+--------+--------------+
    |NAME       |DESCRIPTION |CREATED       |FILTER |ORIGIN  |TAGS          |
    |-----------|------------|--------------|-------|--------|--------------|
    |demo-group |demo-group  |2 minutes ago |links  |default |drink="water" |
    +-----------+------------+--------------+-------+--------+--------------+
    ```
  </CodeGroup>

  * Add a service account to a group using email

  <CodeGroup>
    ```bash Command theme={null}
    cpln group add-member demo-group --serviceaccount controlplane --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +-----------+------------+--------------+-------+--------+--------------+
    |NAME       |DESCRIPTION |CREATED       |FILTER |ORIGIN  |TAGS          |
    |-----------|------------|--------------|-------|--------|--------------|
    |demo-group |demo-group  |2 minutes ago |links  |default |drink="water" |
    +-----------+------------+--------------+-------+--------+--------------+
    ```
  </CodeGroup>
</Accordion>

***

#### group audit

Retrieve audit trail events for the referenced group

**Usage**

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

***

#### group clone

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

**Usage**

```none theme={null}
cpln group 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 group clone demo-group --name demo-group-clone --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +-----------------+--------------------+--------+-------+--------+--------------+
    |NAME             |DESCRIPTION         |CREATED |FILTER |ORIGIN  |TAGS          |
    |-----------------|--------------------|--------|-------|--------|--------------|
    |demo-group-clone |Clone of demo-group |Now     |links  |default |drink="water" |
    +-----------------+--------------------+--------+-------+--------+--------------+
    ```
  </CodeGroup>
</Accordion>

***

#### group create

Create a new group

**Usage**

```none theme={null}
cpln group create --name GROUP_NAME [OPTIONS]
```

<Tip>
  After creating a new group, use the subcommand [add-member](#group-add-member) to populate the group with users and/or service accounts.
</Tip>

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

  Query spec options:
    --query-match     Query filter type  [choices: "all", "none", "any"] [default: "all"]
    --query-property  Property to query
    --query-tag       Tag to query
    --query-rel       Relation to query
    --query-kind      Kind to query  [choices: "user"]

  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 group create --name demo-group --desc demo-group --tag drink=water --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +-----------+------------+--------+-------+--------+--------------+
    |NAME       |DESCRIPTION |CREATED |FILTER |ORIGIN  |TAGS          |
    |-----------|------------|--------|-------|--------|--------------|
    |demo-group |demo-group  |Now     |links  |default |drink="water" |
    +-----------+------------+--------+-------+--------+--------------+
    ```
  </CodeGroup>
</Accordion>

***

#### group delete

Delete one or more referenced groups

**Usage**

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

  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 group delete demo-group --org demo-cpln-organization
    ```

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

***

#### group edit

Edit the referenced group, as YAML, within an editor

**Usage**

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

***

#### group eventlog

Show the event log of the referenced group

**Usage**

```none theme={null}
cpln group 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 group eventlog demo-group --org demo-cpln-organization
    ```

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

***

#### group get

Retrieve one or more referenced groups

**Usage**

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

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

    ```text Output theme={null}
    +-----------------+-----------------------------------------+--------------+-------+--------+--------------+
    |NAME             |DESCRIPTION                              |CREATED       |FILTER |ORIGIN  |TAGS          |
    |-----------------|-----------------------------------------|--------------|-------|--------|--------------|
    |demo-group       |demo-group                               |2 minutes ago |links  |default |drink="water" |
    |demo-group-get-1 |demo-group-get-1                         |Now           |links  |default |              |
    |demo-group-get-2 |demo-group-get-2                         |Now           |links  |default |              |
    |superusers       |Built-in group for all administrators... |5 years ago   |links  |builtin |              |
    |viewers          |Built-in group for read-only access      |5 years ago   |links  |builtin |              |
    +-----------------+-----------------------------------------+--------------+-------+--------+--------------+
    ```
  </CodeGroup>

  * Get one group

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

    ```text Output theme={null}
    +-----------------+-----------------+--------+-------+--------+-----+
    |NAME             |DESCRIPTION      |CREATED |FILTER |ORIGIN  |TAGS |
    |-----------------|-----------------|--------|-------|--------|-----|
    |demo-group-get-1 |demo-group-get-1 |Now     |links  |default |     |
    +-----------------+-----------------+--------+-------+--------+-----+
    ```
  </CodeGroup>

  * Get multiple groups

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

    ```text Output theme={null}
    +-----------------+-----------------+--------+-------+--------+-----+
    |NAME             |DESCRIPTION      |CREATED |FILTER |ORIGIN  |TAGS |
    |-----------------|-----------------|--------|-------|--------|-----|
    |demo-group-get-1 |demo-group-get-1 |Now     |links  |default |     |
    |demo-group-get-2 |demo-group-get-2 |Now     |links  |default |     |
    +-----------------+-----------------+--------+-------+--------+-----+
    ```
  </CodeGroup>
</Accordion>

***

#### group patch

Update the referenced group's metadata using an input file

**Usage**

```none theme={null}
cpln group 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 group patch demo-group --file update.json --org demo-cpln-organization
    ```

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

***

#### group permissions

Show the grantable permissions for a group object type

**Usage**

```none theme={null}
cpln group 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 group permissions --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +-------+-----------------------+-----------------------------------+
    |NAME   |DESCRIPTION            |IMPLIES                            |
    |-------|-----------------------|-----------------------------------|
    |create |Create new groups      |                                   |
    |delete |Delete a group         |                                   |
    |edit   |Modify existing groups |view                               |
    |manage |Full access            |create, delete, edit, manage, view |
    |view   |Read-only view         |                                   |
    +-------+-----------------------+-----------------------------------+
    ```
  </CodeGroup>
</Accordion>

***

#### group query

Find all the groups based on the given query

**Usage**

```none theme={null}
cpln group 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 a group based on the name property

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

    ```text Output theme={null}
    +-----------+------------+--------------+-------+--------+--------------+
    |NAME       |DESCRIPTION |CREATED       |FILTER |ORIGIN  |TAGS          |
    |-----------|------------|--------------|-------|--------|--------------|
    |demo-group |demo-group  |2 minutes ago |links  |default |drink="water" |
    +-----------+------------+--------------+-------+--------+--------------+
    ```
  </CodeGroup>

  * Search for a group based on the description property

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

    ```text Output theme={null}
    +-----------+------------+--------------+-------+--------+--------------+
    |NAME       |DESCRIPTION |CREATED       |FILTER |ORIGIN  |TAGS          |
    |-----------|------------|--------------|-------|--------|--------------|
    |demo-group |demo-group  |3 minutes ago |links  |default |drink="water" |
    +-----------+------------+--------------+-------+--------+--------------+
    ```
  </CodeGroup>

  * Search for a group based on a tag

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

    ```text Output theme={null}
    +-----------+------------+--------------+-------+--------+--------------+
    |NAME       |DESCRIPTION |CREATED       |FILTER |ORIGIN  |TAGS          |
    |-----------|------------|--------------|-------|--------|--------------|
    |demo-group |demo-group  |3 minutes ago |links  |default |drink="water" |
    +-----------+------------+--------------+-------+--------+--------------+
    ```
  </CodeGroup>

  * Search for a group based on a property and tag

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

    ```text Output theme={null}
    +-----------+------------+--------------+-------+--------+--------------+
    |NAME       |DESCRIPTION |CREATED       |FILTER |ORIGIN  |TAGS          |
    |-----------|------------|--------------|-------|--------|--------------|
    |demo-group |demo-group  |3 minutes ago |links  |default |drink="water" |
    +-----------+------------+--------------+-------+--------+--------------+
    ```
  </CodeGroup>
</Accordion>

***

#### group remove-member

Remove members from the referenced group

**Usage**

```none theme={null}
cpln group remove-member <ref> --email USER_EMAIL [OPTIONS]

cpln group remove-member <ref> --serviceaccount SERVICE_ACCOUNT [OPTIONS]
```

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

  Command options:
    --email           Email of user to remove
    --serviceaccount  Name of the service account to remove

  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>
    The user and service account referenced in the examples below were previously added to the group
  </Note>

  * Remove a user to a group

  <CodeGroup>
    ```bash Command theme={null}
    cpln group remove-member demo-group --email test-128@example.com --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +-----------+------------+--------------+-------+--------+--------------+
    |NAME       |DESCRIPTION |CREATED       |FILTER |ORIGIN  |TAGS          |
    |-----------|------------|--------------|-------|--------|--------------|
    |demo-group |demo-group  |3 minutes ago |links  |default |drink="water" |
    +-----------+------------+--------------+-------+--------+--------------+
    ```
  </CodeGroup>

  * Remove a service account to a group using email

  <CodeGroup>
    ```bash Command theme={null}
    cpln group remove-member demo-group --serviceaccount controlplane --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +-----------+------------+--------------+-------+--------+--------------+
    |NAME       |DESCRIPTION |CREATED       |FILTER |ORIGIN  |TAGS          |
    |-----------|------------|--------------|-------|--------|--------------|
    |demo-group |demo-group  |3 minutes ago |links  |default |drink="water" |
    +-----------+------------+--------------+-------+--------+--------------+
    ```
  </CodeGroup>
</Accordion>

***

#### group tag

Manage the tags belonging to one or more referenced groups

**Usage**

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

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

    ```text Output theme={null}
    +-----------------+-----------------+--------+-------+--------+--------------+
    |NAME             |DESCRIPTION      |CREATED |FILTER |ORIGIN  |TAGS          |
    |-----------------|-----------------|--------|-------|--------|--------------|
    |demo-group-tag-1 |demo-group-tag-1 |Now     |links  |default |drink="water" |
    +-----------------+-----------------+--------+-------+--------+--------------+
    ```
  </CodeGroup>

  * Update same tag (after running the example above)

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

    ```text Output theme={null}
    +-----------------+-----------------+--------+-------+--------+---------------+
    |NAME             |DESCRIPTION      |CREATED |FILTER |ORIGIN  |TAGS           |
    |-----------------|-----------------|--------|-------|--------|---------------|
    |demo-group-tag-1 |demo-group-tag-1 |Now     |links  |default |drink="coffee" |
    +-----------------+-----------------+--------+-------+--------+---------------+
    ```
  </CodeGroup>

  * Remove tag (after running the example above)

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

    ```text Output theme={null}
    +-----------------+-----------------+--------+-------+--------+-----+
    |NAME             |DESCRIPTION      |CREATED |FILTER |ORIGIN  |TAGS |
    |-----------------|-----------------|--------|-------|--------|-----|
    |demo-group-tag-1 |demo-group-tag-1 |Now     |links  |default |     |
    +-----------------+-----------------+--------+-------+--------+-----+
    ```
  </CodeGroup>

  * Add same tag to multiple groups

  <CodeGroup>
    ```bash Command theme={null}
    cpln group tag demo-group-tag-1 demo-group-tag-2 --tag multiple-groups=true --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +-----------------+-----------------+--------+-------+--------+-----------------------+
    |NAME             |DESCRIPTION      |CREATED |FILTER |ORIGIN  |TAGS                   |
    |-----------------|-----------------|--------|-------|--------|-----------------------|
    |demo-group-tag-1 |demo-group-tag-1 |Now     |links  |default |multiple-groups="true" |
    |demo-group-tag-2 |demo-group-tag-2 |Now     |links  |default |multiple-groups="true" |
    +-----------------+-----------------+--------+-------+--------+-----------------------+
    ```
  </CodeGroup>

  * Update same tag on multiple groups (after running the example above)

  <CodeGroup>
    ```bash Command theme={null}
    cpln group tag demo-group-tag-1 demo-group-tag-2 --tag multiple-groups=demo-group --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +-----------------+-----------------+--------+-------+--------+-----------------------------+
    |NAME             |DESCRIPTION      |CREATED |FILTER |ORIGIN  |TAGS                         |
    |-----------------|-----------------|--------|-------|--------|-----------------------------|
    |demo-group-tag-1 |demo-group-tag-1 |Now     |links  |default |multiple-groups="demo-group" |
    |demo-group-tag-2 |demo-group-tag-2 |Now     |links  |default |multiple-groups="demo-group" |
    +-----------------+-----------------+--------+-------+--------+-----------------------------+
    ```
  </CodeGroup>

  * Remove same tag from multiple groups (after running the example above)

  <CodeGroup>
    ```bash Command theme={null}
    cpln group tag demo-group-tag-1 demo-group-tag-2 --remove multiple-groups --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +-----------------+-----------------+--------+-------+--------+-----+
    |NAME             |DESCRIPTION      |CREATED |FILTER |ORIGIN  |TAGS |
    |-----------------|-----------------|--------|-------|--------|-----|
    |demo-group-tag-1 |demo-group-tag-1 |Now     |links  |default |     |
    |demo-group-tag-2 |demo-group-tag-2 |Now     |links  |default |     |
    +-----------------+-----------------+--------+-------+--------+-----+
    ```
  </CodeGroup>
</Accordion>

***

#### group update

Update properties of the referenced group

**Usage**

```none theme={null}
cpln group 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
             memberLinks    string[]

             Arrays can be appended to, replaced, or removed using the `+=`, `=`, or `-=` operators, respectively.
    --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 group properties:
    * `description`
      * Description of the group
      * Type: string
    * `tags`
      * Tags (key=value) associated with the group
      * Type: string
    * `memberLinks`
      * Array of links belonging to members of the group
      * Type: string\[]
</Accordion>

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

  ```text theme={null}
  +------------------+------------------+--------+-------+--------+-----+
  |NAME              |DESCRIPTION       |CREATED |FILTER |ORIGIN  |TAGS |
  |------------------|------------------|--------|-------|--------|-----|
  |demo-group-update |demo-group-update |Now     |links  |default |     |
  +------------------+------------------+--------+-------+--------+-----+
  ```

  * Update a group's description

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

    ```text Output theme={null}
    +------------------+----------------+--------+-------+--------+-----+
    |NAME              |DESCRIPTION     |CREATED |FILTER |ORIGIN  |TAGS |
    |------------------|----------------|--------|-------|--------|-----|
    |demo-group-update |new description |Now     |links  |default |     |
    +------------------+----------------+--------+-------+--------+-----+
    ```
  </CodeGroup>

  * Update a group's tags

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

    ```text Output theme={null}
    +------------------+----------------+--------+-------+--------+----------------------+
    |NAME              |DESCRIPTION     |CREATED |FILTER |ORIGIN  |TAGS                  |
    |------------------|----------------|--------|-------|--------|----------------------|
    |demo-group-update |new description |Now     |links  |default |demo-key="demo-value" |
    +------------------+----------------+--------+-------+--------+----------------------+
    ```
  </CodeGroup>

  * Add to a group's member links. This examples adds the built-in controlplane service account

  <CodeGroup>
    ```bash Command theme={null}
    cpln group update demo-group-update --set memberLinks+="/org/demo-cpln-organization/serviceaccount/controlplane" --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +------------------+----------------+--------+-------+--------+----------------------+
    |NAME              |DESCRIPTION     |CREATED |FILTER |ORIGIN  |TAGS                  |
    |------------------|----------------|--------|-------|--------|----------------------|
    |demo-group-update |new description |Now     |links  |default |demo-key="demo-value" |
    +------------------+----------------+--------+-------+--------+----------------------+
    ```
  </CodeGroup>

  * Remove from a group's member links. This examples removes the built-in controlplane service account

  <CodeGroup>
    ```bash Command theme={null}
    cpln group update demo-group-update --set memberLinks-="/org/demo-cpln-organization/serviceaccount/controlplane" --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +------------------+----------------+--------+-------+--------+----------------------+
    |NAME              |DESCRIPTION     |CREATED |FILTER |ORIGIN  |TAGS                  |
    |------------------|----------------|--------|-------|--------|----------------------|
    |demo-group-update |new description |Now     |links  |default |demo-key="demo-value" |
    +------------------+----------------+--------+-------+--------+----------------------+
    ```
  </CodeGroup>
</Accordion>

***