# Turumba CLI

Command-line interface for the [Turumba](https://turumba.net) message automation platform. Manage accounts, delivery channels, messages, templates, groups, conversations, and more -- directly from your terminal or through AI agents.

## Features

- **Full API coverage** -- channels, messages, conversations, templates, group messages, scheduled messages, users, teams, and more
- **Secure authentication** -- tokens stored in your system keyring (macOS Keychain, GNOME Keyring, Windows Credential Manager) with file and environment variable fallbacks
- **Multiple output formats** -- rich terminal tables (default), JSON for scripting, CSV for spreadsheets
- **Filter and sort** -- use the same `field:op:value` filter syntax as the API directly from the CLI
- **AI agent integration** -- built-in `skills` system with structured parameter specs that AI agents can query at runtime
- **Fully scriptable** -- every interactive prompt has a `--flag` equivalent for CI/CD pipelines

## Installation

**Requirements:** Python 3.11+ and an active Turumba account ([turumba.net](https://turumba.net) or `turumba auth register`)

### macOS

```bash
# Install Python (if not already installed)
brew install python@3.12

# Install pipx (recommended for CLI tools)
brew install pipx
pipx ensurepath

# Install Turumba CLI
pipx install turumba
```

### Ubuntu / Debian

```bash
# Install Python and pipx
sudo apt update
sudo apt install python3.12 python3.12-venv pipx
pipx ensurepath

# Install Turumba CLI
pipx install turumba
```

### Fedora / RHEL

```bash
# Install Python and pipx
sudo dnf install python3.12 pipx
pipx ensurepath

# Install Turumba CLI
pipx install turumba
```

### Windows

```powershell
# Install Python from https://www.python.org/downloads/ (check "Add to PATH")

# Install pipx
pip install --user pipx
pipx ensurepath

# Install Turumba CLI
pipx install turumba
```

### Using pip (any OS)

If you prefer pip over pipx, use a virtual environment:

```bash
python3 -m venv ~/.turumba-env
source ~/.turumba-env/bin/activate    # Linux/macOS
# .turumba-env\Scripts\activate       # Windows PowerShell
pip install turumba
```

> **Note:** On macOS and modern Linux, system-wide `pip install` is blocked by [PEP 668](https://peps.python.org/pep-0668/). Use `pipx` (installs in an isolated environment automatically) or a virtual environment as shown above.

### From source (development)

```bash
git clone <repo-url> turumba_cli
cd turumba_cli
python3 -m venv .venv
source .venv/bin/activate             # Linux/macOS
# .venv\Scripts\activate              # Windows PowerShell
pip install -e ".[dev]"
turumba --help                        # Verify installation
```

### Shell Completion

After installing, enable tab completion for your shell:

```bash
# Bash / Zsh / Fish (auto-detected)
turumba --install-completion

# Show the completion script without installing
turumba --show-completion
```

Restart your shell or run `source ~/.bashrc` (or `~/.zshrc`) for completion to take effect.

## Quick Start

```bash
# 1. Log in
turumba auth login
# > Email: you@company.com
# > Password: ********

# 2. Set your default account (avoids passing --account-id every time)
turumba config set default_account_id <your-account-uuid>

# 3. Create a Telegram channel
turumba channels create \
  --name "Support Bot" \
  --type telegram \
  --credentials '{"bot_token": "123456:ABC-DEF"}'

# 4. Send a message
turumba messages create \
  --body "Hello!" \
  --channel-id <channel-uuid> \
  --delivery-address "123456789"

# 5. Check delivery status
turumba messages list -f status:eq:sent -o json
```

## Commands

```
turumba <resource> <action> [options]
```

### Authentication & Configuration

| Command | Description |
|---------|-------------|
| `turumba auth login` | Log in (interactive or via `--email` / `--password`) |
| `turumba auth logout` | Clear stored tokens |
| `turumba auth status` | Show token expiry, user info, active account |
| `turumba auth register` | Create a new Turumba account |
| `turumba auth verify-email` | Verify email with confirmation code |
| `turumba config list` | Show all configuration |
| `turumba config get <key>` | Get a single config value |
| `turumba config set <key> <value>` | Set a config value |
| `turumba config use-account <id>` | Set default account |

### Resources

All resource commands follow the same pattern: `turumba <resource> list|get|create|update|delete`.

| Resource | Description | Requires `account_id` |
|----------|-------------|-----------------------|
| `channels` | Delivery channels (SMS, Telegram, WhatsApp, Email, etc.) | No (auto-injected) |
| `users` | Team members within accounts | Yes |
| `teams` | Teams with member management | Yes |
| `persons` | Recipients with dynamic properties | Yes |
| `contacts` | Contact records with dynamic properties | Yes |
| `messages` | Individual messages (outbound, inbound, system) | Yes |
| `group-messages` | Broadcast messages to groups | Yes |
| `scheduled-messages` | One-time or recurring scheduled messages | Yes |
| `conversations` | Agent-visitor chat threads | Yes |
| `chat-endpoints` | Embeddable chat widgets | No |
| `conversation-configs` | Conversation routing rules | No |
| `groups` | Groups and their membership | No |

> Resources that require `account_id` accept `--account-id / -a`. Set a default with `turumba config set default_account_id <uuid>` to avoid passing it every time.

### Extra Sub-commands

Some resources have additional commands beyond standard CRUD:

```bash
# Channels
turumba channels test-connection --id <id>              # Test existing channel
turumba channels test-connection --type telegram \
  --credentials '{"bot_token": "..."}'                  # Test new credentials

# Teams (member management)
turumba teams list-members <team-id>                    # List team members
turumba teams add-members <team-id> \
  --user-id <uid1> --user-id <uid2> --role member       # Add members
turumba teams remove-members <team-id> \
  --user-id <uid1>                                      # Remove members

# Conversations (message thread)
turumba conversations list-messages <conversation-id>   # List messages in thread
turumba conversations send-message <conversation-id> \
  --body "How can I help?"                              # Send agent reply
turumba conversations send-message <conversation-id> \
  --body "Internal note" --private                      # Private internal note

# Conversation Configs
turumba conversation-configs evaluate \
  --channel-type telegram --channel-id <cid> --known    # Test config matching
```

## Usage Examples

### Channels

```bash
turumba channels list -f channel_type:eq:telegram       # Filter by type
turumba channels create --name "Bot" --type telegram \
  --credentials '{"bot_token": "..."}'                  # Create
turumba channels update <id> --enabled                  # Enable
turumba channels delete <id> --force                    # Delete without prompt
```

### Messages

```bash
turumba messages create --body "Hello!" \
  --channel-id <cid> --delivery-address "+251911..."    # Send outbound
turumba messages list -f status:eq:failed -o json       # Find failed messages
turumba messages get <id> -o json                       # Check delivery details
turumba messages update <id> --status delivered         # Update status
```

### Conversations

```bash
turumba conversations list -f status:eq:open \
  -s last_message_at:desc -o json                       # Open conversations
turumba conversations create --channel-id <cid> \
  --contact-id <contact> --subject "Support"            # Start conversation
turumba conversations update <id> \
  --assignee-id <uid> --status assigned                 # Assign to agent
turumba conversations send-message <id> \
  --body "We're looking into this"                      # Reply
```

### Group Messages

```bash
turumba group-messages create \
  --group-id <gid> --channel-id <cid> \
  --body "Hello everyone!"                              # Broadcast to group
turumba group-messages create \
  --group-id <gid> --template-id <tid> \
  --custom-values '{"promo_code": "MARCH25"}'           # Template-based
```

### Scheduled Messages

```bash
# One-time
turumba scheduled-messages create --send-type single \
  --delivery-address "+251911..." --channel-id <cid> \
  --body "Reminder" --scheduled-at 2026-04-01T09:00:00Z

# Recurring weekly
turumba scheduled-messages create --send-type group \
  --group-id <gid> --channel-id <cid> \
  --body "Weekly update" --scheduled-at 2026-04-07T09:00:00Z \
  --recurring --recurrence-rule RRULE:FREQ=WEEKLY
```

### Users & Teams

```bash
turumba users create --email user@example.com \
  --given-name Abebe --family-name Kebede \
  --role-id <role-uuid>                                 # Create user
turumba teams create --name "Engineering" \
  --lead-id <user-uuid>                                 # Create team
turumba teams add-members <team-id> \
  --user-id <uid1> --user-id <uid2> --role member       # Add members
```

### Persons & Contacts

```bash
turumba persons create \
  --properties '{"name": "Abebe", "phone": "+251911..."}' \
  --group-id <group-id>                                 # Create with group
turumba contacts create \
  --properties '{"phone": "+251...", "email": "a@b.com"}'
```

## Filtering and Sorting

List commands support the Turumba API filter syntax.

### Filters

```bash
--filter field:op:value    # Short: -f
```

| Operator | Description | Example |
|----------|-------------|---------|
| `eq` | Equals | `-f status:eq:connected` |
| `ne` | Not equals | `-f status:ne:disabled` |
| `lt`, `le`, `gt`, `ge` | Comparison | `-f priority:gt:5` |
| `contains` | Substring (case-sensitive) | `-f name:contains:bot` |
| `icontains` | Substring (case-insensitive) | `-f name:icontains:Bot` |
| `startswith` | Starts with | `-f name:startswith:prod` |
| `endswith` | Ends with | `-f email:endswith:@co.com` |
| `in` | In list | `-f channel_type:in:telegram,whatsapp` |
| `is_null` | Is null | `-f assignee_id:is_null:true` |
| `range` | Range | `-f created_at:range:2024-01-01,2024-12-31` |

Combine multiple filters (AND logic):

```bash
turumba channels list -f channel_type:eq:telegram -f status:eq:connected
```

### Sorting

```bash
--sort field:asc|desc      # Short: -s
```

```bash
turumba messages list -s created_at:desc                # Newest first
turumba channels list -s name:asc -s priority:desc      # Multi-sort
```

### Pagination

```bash
turumba messages list --limit 20 --skip 40              # Page 3 (20 items/page)
```

## Output Formats

All list and get commands support `--output / -o`:

| Format | Flag | Use case |
|--------|------|----------|
| `table` | `-o table` | Terminal display (default) |
| `json` | `-o json` | Scripting, AI agents, piping to `jq` |
| `csv` | `-o csv` | Spreadsheets, data analysis |

```bash
turumba channels list                     # Rich table (default)
turumba channels list -o json             # JSON array
turumba channels list -o json | jq '.[0]' # Pipe to jq
turumba channels list -o csv > export.csv # Export to CSV
```

## Configuration

Config is stored in `~/.turumba/config.yaml`.

| Key | Default | Description |
|-----|---------|-------------|
| `gateway_url` | `https://api.dev.turumba.net` | API gateway URL |
| `default_account_id` | *(none)* | Default account for multi-tenant resources |
| `default_output` | `table` | Default output format |

### Environment Variables

For CI/CD and automation:

| Variable | Description |
|----------|-------------|
| `TURUMBA_ACCESS_TOKEN` | JWT access token (skips login entirely) |
| `TURUMBA_REFRESH_TOKEN` | Optional refresh token |

## AI Agent Integration

The CLI includes a built-in **skills system** for AI agents. Instead of hardcoding Turumba knowledge into prompts, agents query the CLI at runtime for parameter specs, examples, and workflows.

```bash
turumba skills list                                     # List all topics
turumba skills show channels -o json                    # Structured specs for agents
turumba skills show create-resource                     # Quick-ref for all creates
turumba skills how-to "send telegram message to group"  # Find best workflow
```

### Available Skill Topics

| Topic | Description |
|-------|-------------|
| `create-resource` | Quick-reference for creating ANY resource |
| `channels` | Delivery channels and credential schemas |
| `users` | User management and role assignment |
| `teams` | Team management and membership |
| `persons` | Persons with dynamic properties |
| `contacts` | Contact records |
| `messages` | Individual message management and delivery tracking |
| `group-messages` | Broadcast messages to groups |
| `scheduled-messages` | One-time and recurring messages |
| `conversations` | Agent-visitor chat threads |
| `chat-endpoints` | Embeddable chat widgets |
| `conversation-configs` | Conversation routing rules |
| `sending` | Overview of all sending methods |
| `auth` | Authentication and login |
| `filtering` | Filter and sort query syntax |
| `overview` | Platform overview and getting started |
| `troubleshooting` | Common issues and debugging tips |

### Setting Up an Agent

Add to your project's `CLAUDE.md` or equivalent:

```markdown
## Turumba CLI
The `turumba` CLI is installed. Use it for all Turumba operations.
- Run `turumba skills show <topic> -o json` for parameter specs
- Run `turumba skills show create-resource -o json` for all creation params
- Run `turumba skills how-to "<task>"` for step-by-step workflows
- Always use `-o json` when parsing output programmatically
```

## Security

### Token Storage

Tokens are stored using a layered approach (first available wins):

1. **System keyring** (recommended) -- macOS Keychain, GNOME Keyring, Windows Credential Manager
2. **File fallback** -- `~/.turumba/credentials` with `0600` permissions
3. **Environment variables** -- `TURUMBA_ACCESS_TOKEN` for CI/CD

### Token Lifecycle

- Access tokens are JWT (RS256, AWS Cognito) with 1-hour expiry
- The CLI checks expiry before every request (5-minute buffer)
- `turumba auth logout` removes tokens from all storage backends

## Development

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

turumba --help                        # Verify installation

ruff check src/                       # Lint
ruff format src/                      # Format
pytest                                # Run tests
pytest --cov=src/turumba_cli          # With coverage
```

## License

MIT
