# CLAUDE.md — Turumba CLI

## Overview

Python CLI for the Turumba message automation platform. Wraps all Turumba API endpoints behind a `turumba <resource> <action>` command interface. Includes a built-in `skills` system with structured parameter specs for AI agent integration.

**Tech Stack**: Python 3.11+, Typer, httpx, Rich, PyYAML, keyring, Pydantic

## Project Structure

```
src/turumba_cli/
├── main.py              # Typer app entry point, command group registration
├── config.py            # ~/.turumba/config.yaml loader/saver
├── credentials.py       # Token storage (keyring -> file -> env var)
├── client.py            # httpx wrapper with auth injection + response envelope parsing
├── output.py            # Table/JSON/CSV formatters (Rich)
├── errors.py            # TurumbaAPIError, TurumbaAuthError, etc.
├── crud_factory.py      # create_crud_commands() generator (Phase 3)
├── commands/            # One module per resource
│   ├── auth.py          # login, logout, register, verify-email, status
│   ├── context.py       # whoami
│   ├── config_cmd.py    # set, get, list, use-account
│   ├── channels.py      # CRUD + test-connection (reference implementation)
│   ├── persons.py       # CRUD (with --account-id)
│   ├── contacts.py      # CRUD (with --account-id)
│   ├── group_messages.py    # CRUD (with --account-id)
│   ├── scheduled_messages.py  # CRUD (with --account-id)
│   ├── chat_endpoints.py     # CRUD
│   ├── conversation_configs.py  # CRUD + evaluate
│   └── skills.py        # Skills system commands (list, show, how-to)
└── skills/              # Interactive skill system for AI agents
    ├── registry.py      # SkillTopic + ParamSpec dataclasses, topic registry, search
    └── topics/          # One module per skill topic (self-registering)
        ├── create_resource.py  # Unified quick-reference for ALL resource creation
        ├── channels.py         # Credential schemas per channel type
        ├── persons.py          # account_id + dynamic properties
        ├── contacts.py         # account_id + properties
        ├── templates.py        # Variable syntax, fallback strategies
        ├── group_messages.py   # Conditional recipient targeting
        ├── scheduled_messages.py  # send-type conditionals, RRULE patterns
        ├── sending.py          # Overview of all sending methods
        └── ...                 # auth, overview, filtering, troubleshooting, etc.
```

## Architecture

- All API calls go through `TurumbaClient` (client.py) which handles auth header injection and response envelope parsing
- The standard Turumba response envelope `{success, data, meta}` is unwrapped by the client — commands receive clean data dicts
- Token storage priority: keyring (macOS Keychain, etc.) -> `~/.turumba/credentials` file (0600 perms) -> `TURUMBA_ACCESS_TOKEN` env var
- Config lives in `~/.turumba/config.yaml`
- Default gateway URL: `https://api.dev.turumba.net`
- Resources needing `account_id` (persons, contacts, group-messages, scheduled-messages) resolve it via `--account-id` flag -> `config.default_account_id` -> error with guidance

## Commands

```bash
turumba auth login|logout|register|verify-email|status
turumba context                    # whoami
turumba config set|get|list|use-account
turumba channels list|get|create|update|delete|test-connection
turumba persons list|get|create|update|delete
turumba contacts list|get|create|update|delete
turumba group-messages list|get|create|update|delete
turumba scheduled-messages list|get|create|update|delete
turumba chat-endpoints list|get|create|update|delete
turumba conversation-configs list|get|create|update|delete|evaluate
turumba skills list|show|how-to
```

## Development

```bash
cd turumba_cli
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

# Run the CLI
turumba --help

# Linting & Formatting
ruff check src/
ruff check --fix src/
ruff format src/

# Testing
pytest
pytest --cov=src/turumba_cli
```

## Code Quality

- Ruff for linting/formatting (config: `ruff.toml`, line length: 100)
- Same rule set as other Turumba services (E, W, F, I, B, C4, UP, ARG, SIM, TCH, PTH, ERA, PL, TRY, RUF)
- `B008` ignored (Typer uses function calls in argument defaults)
- `ERA` enabled: no commented-out code
- Target: 80% test coverage

## Key Patterns

- **Account ID resolution**: Commands needing `account_id` accept `--account-id / -a` and fall back to `config.default_account_id`. Set once via `turumba config set default_account_id <uuid>`
- **Error handling**: Commands catch `TurumbaAPIError`/`TurumbaAuthError`, print friendly messages via `output.error()`, then `raise typer.Exit(1) from None`
- **Output modes**: `--output table` (default, Rich tables), `--output json` (for scripting/agents), `--output csv`
- **Global flags**: `--gateway-url`, `--output`, `--filter`, `--sort`, `--limit`, `--skip`, `--account-id`
- **Interactive prompts**: All prompts have `--flag` equivalents for non-interactive use
- **Skills system**: `SkillTopic` with `ParamSpec` create_params, notes, examples, workflows. Agents query `turumba skills show <topic> -o json` for structured parameter specs
- **CRUD factory** (Phase 3): `create_crud_commands()` will generate list/get/create/update/delete for a resource given its API path and column config

## Adding a New Resource Command

1. Create `src/turumba_cli/commands/<resource>.py`
2. Define `app = typer.Typer(name="<resource>", help="...")`
3. Define `API_PATH` and `LIST_COLUMNS`
4. Add CRUD commands following `channels.py` as reference
5. If resource needs `account_id`: add `--account-id / -a` with `get_value("default_account_id")` fallback
6. Register in `main.py`: `app.add_typer(<resource>.app)`
7. Create skill topic in `skills/topics/<resource>.py` with `create_params` and `notes`
8. Register import in `skills/topics/__init__.py`
9. Update `create_resource.py` notes with the new resource's required params
