Skip to main content
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. Define groups alongside your policy files and apply them together: 
# 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

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

# 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

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)
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: 
agent-charley-cli effective <device_id>
You can also list all devices with the Charley REST API: 
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) for the UI walkthrough. Dashboard-created groups are fully compatible with the CLI/SDK — you can manage membership from either interface.