turumba 0.1.1

CLI for the Turumba message automation platform

Turumba CLI

Command-line interface for the Turumba 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 or turumba auth register)

macOS

# 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

# 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

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

# Install Turumba CLI
pipx install turumba

Windows

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

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. Use pipx (installs in an isolated environment automatically) or a virtual environment as shown above.

From source (development)

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

# 1. Log in
turumba auth login
# > Email: [e-mail]
# > 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:

# 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

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

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

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

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

# 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

turumba users create --email [e-mail] \
  --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

turumba persons create \
  --properties '{"name": "Abebe", "phone": "+251911..."}' \
  --group-id <group-id>                                 # Create with group
turumba contacts create \
  --properties '{"phone": "+251...", "email": "[e-mail]"}'

Filtering and Sorting

List commands support the Turumba API filter syntax.

Filters

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

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

Sorting

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

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

Pagination

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

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.

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:

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

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