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

# CLI Reference

> Complete reference for all agent-charley-cli CLI commands and flags

## Installation

```bash theme={null}
pip install charley_policy-0.1.0-py3-none-any.whl
```

## Global Options

These options apply to every command and must come **before** the subcommand:

```
agent-charley-cli [OPTIONS] COMMAND [ARGS]...
```

| Option              | Env var            | Default                           | Description                                |
| ------------------- | ------------------ | --------------------------------- | ------------------------------------------ |
| `--api-key TEXT`    | `CHARLEY_API_KEY`  | —                                 | API key (required)                         |
| `--env [prod\|dev]` | `CHARLEY_ENV`      | `prod`                            | Target environment shortcut                |
| `--base-url TEXT`   | `CHARLEY_BASE_URL` | `https://dash.charlemagnelabs.ai` | Override API base URL                      |
| `--env-file TEXT`   | —                  | `.env`                            | dotenv file to load `CHARLEY_*` vars from  |
| `--verbose, -v`     | —                  | `false`                           | Print request URL and key prefix to stderr |

### Environment shortcuts

| `--env` | Base URL                              |
| ------- | ------------------------------------- |
| `prod`  | `https://dash.charlemagnelabs.ai`     |
| `dev`   | `https://dash.dev.charlemagnelabs.ai` |

`--env` takes precedence over `--base-url`.

***

## `plan`

Preview what would change if you ran `apply`. Makes **no changes** to the server.

```bash theme={null}
agent-charley-cli plan --file <path> [--groups <path>] [--prune]
```

| Flag              | Description                                                   |
| ----------------- | ------------------------------------------------------------- |
| `--file, -f TEXT` | Policy YAML/JSON file or directory of files (required)        |
| `--groups TEXT`   | Groups YAML file                                              |
| `--prune`         | Include deletions for server policies not present in the file |

**Output:** a summary (`N to create, N to update, N to delete, N unchanged`) followed by a unified diff of all changes.

```bash theme={null}
# Preview all policy changes
agent-charley-cli plan --file policies/

# Preview policies + group membership changes
agent-charley-cli plan --file policies/ --groups groups.yaml

# Include deletions (what would be removed from the server)
agent-charley-cli plan --file policies/ --prune
```

***

## `apply`

Apply local policy files to the server. Shows a plan first and prompts to confirm (skip with `-y`).

```bash theme={null}
agent-charley-cli apply --file <path> [--groups <path>] [--prune] [-y]
```

| Flag              | Description                                            |
| ----------------- | ------------------------------------------------------ |
| `--file, -f TEXT` | Policy YAML/JSON file or directory of files (required) |
| `--groups TEXT`   | Groups YAML file (creates groups and sets membership)  |
| `--prune`         | Delete server policies not present in the file         |
| `--yes, -y`       | Skip confirmation prompt                               |

```bash theme={null}
# Apply with confirmation prompt
agent-charley-cli apply --file policies/

# Apply without prompting (CI usage)
agent-charley-cli apply --file policies/ --groups groups.yaml --prune -y
```

<Warning>
  `--prune` deletes any server policy not represented in your local files. Use it carefully — it will remove policies that were created via the dashboard or by another operator.
</Warning>

***

## `pull`

Download the current server policies and write them to a local YAML file. Useful for bootstrapping a GitOps repo from an existing dashboard configuration.

```bash theme={null}
agent-charley-cli pull [--output <path>]
```

| Flag                | Default         | Description      |
| ------------------- | --------------- | ---------------- |
| `--output, -o TEXT` | `policies.yaml` | Output file path |

```bash theme={null}
# Pull to default file
agent-charley-cli pull

# Pull to a specific path
agent-charley-cli pull --output policies/current.yaml
```

***

## `effective`

Show the effective merged policy for a specific device — the combined result of global + group + device layers.

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

Output is a JSON object keyed by policy type:

```json theme={null}
{
  "app_config": { "policy_data": { "flow_logs_enabled": true, ... } },
  "dlp_config":  { "policy_data": { "enabled": true, ... } },
  "flow_config": { "policy_data": { "enabled": true, ... } }
}
```

```bash theme={null}
agent-charley-cli effective a1b2c3d4-e5f6-7890-abcd-ef1234567890
```

***

## `groups list`

List all groups in the org.

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

Output: one line per group showing name, UUID, source, and description.

***

## `groups create`

Create a new group.

```bash theme={null}
agent-charley-cli groups create <name> [--description TEXT] [--idp-group-id TEXT]
```

| Flag                     | Description                                            |
| ------------------------ | ------------------------------------------------------ |
| `--description, -d TEXT` | Optional description                                   |
| `--idp-group-id TEXT`    | Pre-wire an IDP group mapping (stored, not yet active) |

***

## `groups delete`

Delete a group. Prompts for confirmation unless `--yes` is passed.

```bash theme={null}
agent-charley-cli groups delete <name_or_id> [--yes]
```

***

## `groups add-members`

Add members to a group by email or device UUID. At least one `--email` or `--device-id` is required.

```bash theme={null}
agent-charley-cli groups add-members <name_or_id> \
  --email alice@company.com \
  --email bob@company.com \
  --device-id <uuid>
```

***

## `groups remove-members`

Remove specific members from a group.

```bash theme={null}
agent-charley-cli groups remove-members <name_or_id> \
  --email alice@company.com
```

***

## `groups set-members`

Replace the full member list for a group. Any devices currently in the group but not in this call are removed.

```bash theme={null}
agent-charley-cli groups set-members <name_or_id> \
  --email alice@company.com \
  --device-id <uuid>
```

***

## `groups list-devices`

List the device UUIDs currently assigned to a group.

```bash theme={null}
agent-charley-cli groups list-devices <name_or_id>
```

### `groups list-members`

List all members of a group with full user and device details — email, display name, machine ID, and enrollment status. Useful for auditing who is in a group and verifying user-to-device mappings.

```bash theme={null}
agent-charley-cli groups list-members <name_or_id>
```

**Example output:**

```
DEVICE ID                             EMAIL                         NAME                          MACHINE         STATUS
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
a1b2c3d4-e5f6-7890-abcd-ef1234567890  alice@company.com             Alice Smith                   ALICE-MBP       active
b2c3d4e5-f6a7-8901-bcde-f12345678901  bob@company.com               Bob Jones                     BOB-MBA         active
```

***

## Exit Codes

| Code | Meaning                                                           |
| ---- | ----------------------------------------------------------------- |
| `0`  | Success                                                           |
| `1`  | Error (auth failure, API error, file parse error, user cancelled) |