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

# Getting Started

> Install the CLI and deploy your first Charley policy in under 5 minutes

## Prerequisites

* Python 3.10 or later
* A Charley account with **Org Admin** role
* An API key (see [API Keys](/policy-as-code/authentication))

## Install

The SDK is distributed as a Python wheel. Download `charley_policy-*.whl` from **Settings → API Keys → Download SDK** in the Charley dashboard, then:

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

Verify:

```bash theme={null}
agent-charley-cli --help
```

## Set Your API Key

```bash theme={null}
export CHARLEY_API_KEY=ck_live_...
```

Or create a `.env` file in your working directory — the CLI loads it automatically:

```
CHARLEY_API_KEY=ck_live_...
```

## Your First Policy File

Create `policies/global.yaml`:

```yaml theme={null}
- name: Global Baseline
  type: app_config
  scope: global
  locked: false
  data:
    flow_logs_enabled: true
    suppress_frontend_ui: false

- name: Global DLP
  type: dlp_config
  scope: global
  locked: false
  data:
    enabled: true
    targets:
      apply_to_all_apps: true
    detections:
      builtins: [credit_card, ssn_us]
    actions:
      mode: warn
```

## Preview Changes

Before applying anything, run a plan to see what would change:

```bash theme={null}
agent-charley-cli plan --file policies/
```

Sample output:

```
Plan: 2 to create, 0 to update, 0 to delete, 0 unchanged.

--- /dev/null
+++ Global Baseline (global/app_config)
@@ -1,4 +1,4 @@
+ flow_logs_enabled: true
+ suppress_frontend_ui: false
...
```

## Apply

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

You'll see a diff and be prompted to confirm. Skip the prompt with `-y`:

```bash theme={null}
agent-charley-cli apply --file policies/ -y
```

## Download Existing Policies

If your org already has policies configured in the dashboard, pull them down as a starting point:

```bash theme={null}
agent-charley-cli pull --output policies/current.yaml
```

Edit the output, then run `plan` to see what your edits would change.

## Add Group Policies

Create `groups.yaml` alongside your policies:

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

Add a group-scoped policy:

```yaml theme={null}
# policies/finance.yaml
- name: Finance DLP
  type: dlp_config
  scope: group
  target: finance
  locked: true
  data:
    enabled: true
    detections:
      builtins: [credit_card, ssn_us, phone]
    actions:
      mode: block
```

Apply both together:

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

## Recommended File Layout

```
charley/
├── groups.yaml
└── policies/
    ├── global.yaml        # org-wide baseline
    ├── finance.yaml       # finance group overrides
    └── engineering.yaml   # engineering group overrides
```

## Troubleshooting

Add `--verbose` to any command to see the base URL and key prefix being used:

```bash theme={null}
agent-charley-cli --verbose plan --file policies/
```

For the dev environment:

```bash theme={null}
agent-charley-cli --env dev plan --file policies/
```

Common errors:

| Error                     | Cause                                         |
| ------------------------- | --------------------------------------------- |
| `401 Unauthorized`        | API key is missing, invalid, or expired       |
| `403 Forbidden`           | Using a `read_only` key for a write operation |
| `Connection refused`      | Wrong `--base-url` or `--env`                 |
| `Failed to load policies` | YAML parse error — check indentation          |

## Next Steps

* [API Keys](/policy-as-code/authentication) — key types, rotation, CI secrets
* [Policy Reference](/policy-as-code/policy-reference) — all fields for each policy type
* [Groups](/policy-as-code/groups) — manage device groups via CLI and YAML
* [CLI Reference](/policy-as-code/cli-reference) — all commands and flags
* [Examples](/policy-as-code/examples) — copy-paste templates
* [End-to-End Testing Guide](/policy-as-code/testing-guide) — verify your setup against a real device