Getting Started

Prerequisites

Python 3.10 or later
A Charley account with Org Admin role
An API key (see API Keys)

Install

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

pip install charley_policy-0.1.0-py3-none-any.whl

Verify:

agent-charley-cli --help

Set Your API Key

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:

- 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:

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

agent-charley-cli apply --file policies/

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

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:

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:

- name: finance
  description: "Finance team devices"
  members:
    - alice@yourcompany.com
    - bob@yourcompany.com

Add a group-scoped policy:

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

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:

agent-charley-cli --verbose plan --file policies/

For the dev environment:

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 — key types, rotation, CI secrets
Policy Reference — all fields for each policy type
Groups — manage device groups via CLI and YAML
CLI Reference — all commands and flags
Examples — copy-paste templates
End-to-End Testing Guide — verify your setup against a real device

Overview

Dashboard

Policy as Code

Integrations

API Reference

Self-Hosting

Prerequisites

Install

Set Your API Key

Your First Policy File

Preview Changes

Apply

Download Existing Policies

Add Group Policies

Recommended File Layout

Troubleshooting

Next Steps

​Prerequisites

​Install

​Set Your API Key

​Your First Policy File

​Preview Changes

​Apply

​Download Existing Policies

​Add Group Policies

​Recommended File Layout

​Troubleshooting

​Next Steps

Prerequisites

Install

Set Your API Key

Your First Policy File

Preview Changes

Apply

Download Existing Policies

Add Group Policies

Recommended File Layout

Troubleshooting

Next Steps