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

# Groups

> Create and manage device groups for scoped policy delivery via CLI and SDK

Groups apply a policy override to a segment of your device fleet. A device belongs to **at most one group** at a time. Removing a device from a group (or deleting the group) immediately returns that device to the org-wide policy.

## Scope Hierarchy

```
global → group → device
```

A group policy overrides the same field in the org-wide policy. A device policy overrides both. Unset fields always fall through to the broader scope.

## Managing Groups via YAML (Recommended)

Define groups alongside your policy files and apply them together:

```yaml theme={null}
# groups.yaml
- name: finance
  description: "Finance team devices"
  members:
    - alice@yourcompany.com
    - bob@yourcompany.com

- name: engineering
  description: "Engineering team"
  members:
    - eng-lead@yourcompany.com
    - device_id: a1b2c3d4-e5f6-...   # target a specific device UUID
```

```bash theme={null}
agent-charley-cli apply --file policies/ --groups groups.yaml
```

On apply, the CLI will:

1. Create any groups that don't exist yet.
2. Set the member list for each group (using `set_members`, which replaces existing membership).

Members can be specified as email addresses (all active devices enrolled by that user are added) or explicit device UUIDs.

## Managing Groups via CLI

```bash theme={null}
# List all groups
agent-charley-cli groups list

# Create a group
agent-charley-cli groups create finance --description "Finance team devices"

# Add members
agent-charley-cli groups add-members finance \
  --email alice@company.com \
  --email bob@company.com \
  --device-id a1b2c3d4-e5f6-...

# Replace the full member list
agent-charley-cli groups set-members finance \
  --email alice@company.com

# Remove specific members
agent-charley-cli groups remove-members finance --email bob@company.com

# List device UUIDs in a group
agent-charley-cli groups list-devices finance

# List members with user details (email, name, machine ID, status)
agent-charley-cli groups list-members finance

# Delete a group
agent-charley-cli groups delete finance --yes
```

## Managing Groups via Python SDK

```python theme={null}
from charley_policy import CharleyClient

with CharleyClient() as client:
    # Create
    group = client.groups.create("finance", description="Finance team")

    # Add members by email or device UUID
    client.groups.add_members("finance",
        emails=["alice@company.com"],
        device_ids=["a1b2c3d4-e5f6-..."],
    )

    # Replace full member list
    client.groups.set_members("finance", emails=["alice@company.com"])

    # Remove members
    client.groups.remove_members("finance", emails=["bob@company.com"])

    # List device UUIDs in the group
    device_ids = client.groups.list_devices("finance")

    # List members with user details (email, name, machine ID, status)
    members = client.groups.list_members("finance")
    for m in members:
        print(m["enrolled_email"], m["device_id"], m["status"])

    # Rename or update description
    client.groups.update("finance", description="Finance & treasury")

    # Delete
    client.groups.delete("finance")
```

## Deleting a Group

Deleting a group:

* Removes all device assignments immediately
* Does **not** delete associated policies — they become orphaned and are ignored
* Devices fall back to the org-wide policy immediately (agent picks this up on the next policy poll)

```bash theme={null}
agent-charley-cli groups delete finance --yes
```

## Getting Device UUIDs

Device UUIDs are available in the dashboard under **Devices** (the short ID under each device name), or via the API:

```bash theme={null}
agent-charley-cli effective <device_id>
```

You can also list all devices with the Charley REST API:

```bash theme={null}
curl https://dash.charlemagnelabs.ai/api/devices \
  -H "x-api-key: ck_live_..."
```

## Dashboard Management

Groups can also be created and managed in the dashboard under **Devices → Groups**. See [Groups (Dashboard)](/dashboard/groups) for the UI walkthrough.

Dashboard-created groups are fully compatible with the CLI/SDK — you can manage membership from either interface.