botix-cli 1.0.0

Командная строка для BOTIX Public API

botix-cli

Командная строка для BOTIX Public API. Делает то же, что веб-кабинет app.botix.pro, но из терминала: создание ключей, управление подписками webhook, list контактов, отправка сообщений, тестовые доставки. Аналоги — stripe-cli, gh, aws-cli.

Требования

• Python 3.9+
• Действующий API-ключ BOTIX (получается в кабинете в разделе «Настройки → API-ключи»)

Установка

pip install botix-cli

После установки команда botix доступна глобально.

Проверка:

botix --version

Первый запуск

botix login
# API-ключ (btx_live_... или btx_test_...): ********
# ✓ Профиль default сохранён (project_id=42).

Ключ кладётся в ~/.botix/config.yaml с правами 600 (читает только владелец).

Проверка авторизации:

botix whoami

Команды

Профили (auth)

Команда	Что делает
botix login	Сохранить API-ключ. Проверяет через GET /me
botix login --name staging	Создать дополнительный профиль
botix logout	Удалить весь конфиг
botix logout --name staging	Удалить один профиль
botix whoami	project_id, scopes, тариф активного ключа

Контакты

botix contacts list --tag VIP --channel telegram --limit 50
botix contacts get 42
botix contacts create --first-name "Иван" --phone "[phone]" --tag VIP
botix contacts delete 42 --yes

Сообщения

botix messages send --contact-id 42 --channel telegram --text "Привет!"
botix messages list --contact-id 42 --limit 50

messages send автоматически использует Idempotency-Key — повтор той же команды не отправит сообщение второй раз.

Webhooks

botix webhooks list
botix webhooks create \
  --url https://example.com/hook \
  --events contact.created,message.received
botix webhooks test 7              # отправить тестовое событие
botix webhooks tail                # live-лента доставок (аналог `stripe listen`)
botix webhooks delete 7 --yes

webhooks tail опрашивает /api/v1/webhook-deliveries раз в 2 секунды (можно настроить флагом --interval) и печатает новые доставки в реальном времени. Прерывается через Ctrl+C.

API-ключи

botix keys list
botix keys create --name "Production" --scopes contacts:read,messages:send
botix keys revoke 12 --yes

Управление ключами — внутренняя возможность кабинета. Если ваш ключ не имеет прав keys:manage, CLI попросит создать ключ через app.botix.pro/settings?tab=api-keys.

Профили

Несколько профилей живут в одном ~/.botix/config.yaml:

default_profile: production
profiles:
  production:
    api_key: btx_live_...
    base_url: https://api.botix.pro
  staging:
    api_key: btx_test_...
    base_url: https://api.botix.pro

Выбрать профиль на конкретный вызов:

botix --profile staging contacts list

Переменные окружения

Переменная	Эффект
BOTIX_API_KEY	Полностью обходит конфиг — удобно для CI
BOTIX_BASE_URL	Базовый URL API (по умолчанию https://api.botix.pro)
BOTIX_PROFILE	Имя профиля по умолчанию (эквивалент --profile)
BOTIX_CONFIG_DIR	Каталог конфигурации (для тестов и изолированных сред)

Пример использования в GitHub Actions:

- name: Отправить уведомление через BOTIX
  env:
    BOTIX_API_KEY: ${{ secrets.BOTIX_API_KEY }}
  run: |
    botix messages send --contact-id 42 --text "Деплой прошёл успешно"

Machine-readable вывод

Любая команда поддерживает флаг --json — печатает JSON вместо таблиц:

botix --json contacts list | jq '.[] | select(.tags | index("VIP"))'

Полезно для интеграций и скриптов.

FAQ

Где хранится ключ? ~/.botix/config.yaml, права 600 (читает только владелец).

Как удалить ключ полностью? botix logout --yes (удаляет весь файл) или botix logout --name production --yes (один профиль).

Можно ли использовать в CI без ~/.botix? Да, передайте BOTIX_API_KEY через переменные окружения. login тогда не нужен.

Что делать если 401 Unauthorized?

1. Проверьте botix whoami — что ключ корректный.
2. Проверьте scopes ключа в кабинете app.botix.pro/settings?tab=api-keys — у разных команд CLI разные требования (contacts:read для list, messages:send для send и т.д.).

botix webhooks tail ничего не показывает. Доставки появляются только при работе webhook. Запустите рядом botix webhooks test <id> — должна сразу появиться доставка.

Разработка

git clone https://github.com/BOTIX-pro/cli.git
cd cli
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest

CI прогоняет тесты на Python 3.9 — 3.12 (см. .github/workflows/test.yml).

Лицензия

MIT — см. LICENSE.

Ссылки

• Сайт: botix.pro
• Документация API: botix.pro/docs
• SDK (Python): github.com/BOTIX-pro/sdk-python
• Issues: github.com/BOTIX-pro/cli/issues