# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

CrowdSec Cloudflare Bouncer Manager (`cf-bouncer-manager`) is a Korean-language CLI tool for managing the CrowdSec Cloudflare Worker Bouncer. It manages protected domains, Turnstile CAPTCHA settings, and bouncer configuration through Incus/LXD containers.

## Development Commands

```bash
# Run the CLI (via uv package manager)
uv run python cf_bouncer.py [command] [options]

# Or use the wrapper script
./cfb [command] [options]

# Install dependencies
uv sync
```

## Architecture

**Runtime Environment:**
- Python 3.13+ with `uv` as the package manager
- Interacts with Incus/LXD containers: `cs-cf-worker-bouncer` (bouncer service) and `crowdsec` (security engine)
- Configuration stored at `/etc/crowdsec/bouncers/crowdsec-cloudflare-worker-bouncer.yaml` inside the container

**Key Components in cf_bouncer.py:**
- **CLI Framework:** Typer with Rich console output
- **Container Interaction:** `run_incus()` wrapper for all container commands with 60s timeout
- **Config Management:** YAML read/write via Incus exec, automatic backup before writes (keeps 20)
- **Cloudflare API:** Domain/zone queries with pagination support, 30s request timeout
- **Audit Logging:** All actions logged to `~/cf-bouncer-manager/history.log`

**Data Flow:**
1. CLI command → Read config from container via Incus
2. Modify config in memory
3. Backup existing config → Write new config → Optionally restart service via `do_apply()`

## CLI Commands

`list`, `show`, `add`, `edit`, `remove` - Domain CRUD operations
`sync` - Bulk import all Cloudflare zones
`apply` - Restart bouncer service to apply changes
`status` - Check bouncer process and CrowdSec status
`available` - List unprotected Cloudflare domains
`logs [-f]` - View bouncer logs (with optional follow)
`decisions`, `metrics` - CrowdSec data queries
`backup`, `restore`, `diff` - Configuration backup management
`export` - Export domain list to YAML/JSON
`history` - View action history

## Dependencies

Core: `typer`, `pyyaml`, `requests`, `rich` (see pyproject.toml)

## External Requirements

- Incus/LXD with containers: `cs-cf-worker-bouncer`, `crowdsec`
- Cloudflare API token configured in bouncer YAML
- Access to `/etc/crowdsec/bouncers/` directory