CLI Reference

BioETL command-line interface (CLI) - основной способ взаимодействия с системой. Построен на фреймворке Click для стабильности и расширяемости.

Версия: 6.0.0 Дата обновления: 2026-03-02

Запуск CLI

# Рекомендуемый способ (после установки)
bioetl <command> [options]

# Или во время разработки
python -m bioetl.interfaces.cli <command> [options]

Для справки по любой команде добавьте --help:

bioetl --help
bioetl run --help

Команды

`run` — Запуск одного пайплайна

Выполняет ETL-пайплайн для указанной сущности.

Синтаксис:

bioetl run --pipeline <NAME> [OPTIONS]

Обязательные параметры:

Параметр	Описание
`--pipeline <NAME>`	Имя пайплайна (соответствует YAML в `configs/entities/`)

Опции:

Опция	Тип	По умолчанию	Описание
`--run-type`	choice	`incremental`	Тип запуска: `incremental`, `backfill`, `rebuild`
`--limit`	int	None	Максимальное количество записей
`--resume`	flag	False	Продолжить с последнего checkpoint
`--dry-run`	flag	False	Предпросмотр без записи данных
`--yes`, `-y`	flag	False	Пропустить подтверждение для rebuild/backfill
`--input-csv`	path	None	Путь к CSV с ID для фильтрации
`--filter-column`	str	`id`	Имя колонки в CSV с ID
`--filter-field`	str	varies	Поле API для фильтрации
`--vacuum-after-run`	flag	None	Запустить VACUUM после успешного выполнения
`--vacuum-retention-days`	int	7	Retention для VACUUM (дней)
`--debug`	flag	False	Включить DEBUG логирование
`--health-server/--no-health-server`	flag	True	Включить HTTP health server
`--health-port`	int	8081	Порт для health server

Примеры:

# Инкрементальный запуск (по умолчанию)
bioetl run --pipeline chembl_activity

# С ограничением записей (для тестирования)
bioetl run --pipeline chembl_activity --limit 100

# Полная перезагрузка данных
bioetl run --pipeline chembl_activity --run-type rebuild --yes

# Предпросмотр очистки без выполнения
bioetl run --pipeline chembl_activity --run-type rebuild --dry-run

# Продолжить прерванный запуск
bioetl run --pipeline chembl_activity --resume

# С фильтрацией по CSV
bioetl run --pipeline chembl_activity \
    --input-csv data/filter-ids.csv \
    --filter-column molecule-id \
    --filter-field molecule-chembl-id

# С DEBUG логированием
bioetl run --pipeline chembl_activity --debug

Типы запуска:

Тип	Описание	Очистка данных
`incremental`	Обработка новых записей с последнего checkpoint	Нет
`backfill`	Обработка определённого диапазона	Silver/Gold
`rebuild`	Полная перезагрузка всех данных	Bronze/Silver/Gold

Exit Codes:

Код	Значение
0	Успешное выполнение
82	Ошибка выполнения пайплайна
83	Превышен порог Data Quality
84	Ошибка захвата блокировки
86	Сетевая ошибка
130	Прервано (Ctrl+C)

`run-all` — Запуск всех пайплайнов провайдера

Последовательно выполняет все пайплайны для указанного провайдера.

Синтаксис:

bioetl run-all --source <PROVIDER> [OPTIONS]

Опции:

Опция	Тип	По умолчанию	Описание
`--source`	str	Required	Имя провайдера (chembl, pubchem, uniprot и др.)
`--run-type`	choice	`incremental`	Тип запуска
`--limit`	int	None	Лимит записей для каждого пайплайна
`--dry-run`	flag	False	Показать пайплайны без выполнения
`--yes`, `-y`	flag	False	Пропустить подтверждение
`--list-only`	flag	False	Только показать список пайплайнов
`--debug`	flag	False	DEBUG логирование

Примеры:

# Запуск всех ChEMBL пайплайнов
bioetl run-all --source chembl

# Только просмотр списка
bioetl run-all --source chembl --list-only

# Предпросмотр
bioetl run-all --source pubchem --dry-run

# Rebuild всех пайплайнов провайдера
bioetl run-all --source chembl --run-type rebuild --yes

`run-composite` — Запуск композитных пайплайнов

Выполняет композитный пайплайн (seed + enrichers) согласно ADR-026.

Синтаксис:

bioetl run-composite --composite <NAME> [OPTIONS]

Опции:

Опция	Тип	По умолчанию	Описание
`--composite`	str	Required	Имя композитного пайплайна
`--resume`	flag	False	Продолжить с checkpoint
`--dry-run`	flag	False	Предпросмотр без записи
`--seed-limit`	int	None	Лимит записей для seed пайплайна
`--enrich-only`	str	None	Запустить только указанные enrichers (через запятую)
`--required-only`	flag	False	Пропустить опциональные enrichers
`--force-enricher`	str	None	Принудительный перезапуск enricher
`--debug`	flag	False	DEBUG логирование

Примеры:

# Запуск композитного пайплайна публикаций
bioetl run-composite --composite publication

# С ограничением seed
bioetl run-composite --composite publication --seed-limit 100

# Только определённые enrichers
bioetl run-composite --composite publication --enrich-only crossref,openalex

# Только обязательные enrichers
bioetl run-composite --composite publication --required-only

`adr` — Работа с ADR

Утилиты для просмотра и валидации архитектурных решений (Architecture Decision Records).

`adr list` — Список ADR

bioetl adr list [--json]

`adr show` — Просмотр ADR

bioetl adr show <NUMBER> [--raw]

`adr validate` — Валидация ADR репозитория

bioetl adr validate [--json]

`export` — Экспорт данных

Экспортирует Delta-таблицы Silver/Gold в CSV, XLSX или TSV.

Синтаксис:

bioetl export [TABLE] [OPTIONS]

Аргументы:

Аргумент	Описание
`TABLE`	Имя таблицы в формате `provider.entity` (опционально при `--list`)

Опции:

Опция	Тип	По умолчанию	Описание
`--list`	flag	False	Показать все доступные таблицы
`--preview`	flag	False	Показать схему и sample данных
`--format`, `-f`	choice	`csv`	Формат: `csv`, `xlsx`, `tsv`
`--layer`, `-l`	choice	`silver`	Слой: `silver`, `gold`
`--output`, `-o`	path	`data/exports`	Директория для экспорта
`--limit`	int	None	Максимальное количество строк
`--columns`, `-c`	str	None	Колонки для экспорта (через запятую)

Примеры:

# Список всех таблиц
bioetl export --list

# Предпросмотр таблицы
bioetl export chembl.activity --preview

# Экспорт в CSV (по умолчанию)
bioetl export chembl.activity

# Экспорт в Excel
bioetl export chembl.activity --format xlsx

# С ограничением строк и колонок
bioetl export chembl.activity --limit 10000 --columns id,name,value

# Экспорт Gold-слоя
bioetl export chembl.activity --layer gold

# В указанную директорию
bioetl export chembl.activity -o ./my-exports

`config` — Управление конфигурацией

Просмотр и валидация конфигурации пайплайнов.

`config show` — Показать конфигурацию пайплайна

bioetl config show <PIPELINE> [--format yaml|json]

Примеры:

bioetl config show chembl_activity
bioetl config show chembl_activity --format json

`config validate` — Валидация конфигурации

bioetl config validate <PIPELINE>

Выводит: Provider, Entity type, Silver table, Gold table (если есть).

`config show-settings` — Глобальные настройки

bioetl config show-settings [--format yaml|json]

Показывает все BIOETL-* переменные окружения (API-ключи маскируются).

`config list-pipelines` — Список пайплайнов

bioetl config list-pipelines

`quarantine` — Управление карантином

Dashboard для работы с проблемными записями.

`quarantine inspect` — Просмотр записей

bioetl quarantine inspect --pipeline <NAME> [OPTIONS]

Опция	Тип	По умолчанию	Описание
`--pipeline`	str	Required	Имя пайплайна
`--limit`	int	100	Максимум записей
`--error-code`	str	None	Фильтр по коду ошибки

Примеры:

bioetl quarantine inspect --pipeline chembl_activity
bioetl quarantine inspect --pipeline chembl_activity --error-code DQ-MISSING-FIELD

`quarantine stats` — Статистика

bioetl quarantine stats --pipeline <NAME> [--json]

Показывает: общее количество, распределение по кодам ошибок, статусы (NEW, REVIEWED, RESOLVED).

`quarantine replay` — Повторная обработка

bioetl quarantine replay --pipeline <NAME> [OPTIONS]

Опция	Тип	По умолчанию	Описание
`--pipeline`	str	Required	Имя пайплайна
`--error-code`	str	None	Фильтр по коду ошибки
`--max-age-days`	int	7	Максимальный возраст записей
`--dry-run`	flag	False	Предпросмотр

`quarantine purge` — Удаление старых записей

bioetl quarantine purge --pipeline <NAME> [OPTIONS]

Опция	Тип	По умолчанию	Описание
`--older-than-days`	int	30	Удалить записи старше N дней
`--dry-run`	flag	False	Предпросмотр
`--force`	flag	False	Без подтверждения

`quarantine resolve` — Пометить как решённое

bioetl quarantine resolve --pipeline <NAME> --payload-hash <HASH> [--status IGNORED|REPROCESSED]

`checkpoint` — Управление checkpoint

`checkpoint list` — Список checkpoint

bioetl checkpoint list --pipeline <NAME>

`health` — Health checks

`health server` — HTTP health server

bioetl health server [--host 127.0.0.1] [--port 8081]

Endpoints:

GET /health — общий статус
GET /health/live — Kubernetes liveness probe
GET /health/ready — Kubernetes readiness probe
GET /health/providers — детальный статус провайдеров

`health check` — Проверка провайдеров

bioetl health check [--provider chembl] [--json]

Проверяет connectivity и health всех или указанных провайдеров.

Примеры:

bioetl health check
bioetl health check --provider chembl --provider pubchem
bioetl health check --json

`lock` — Управление блокировками

`lock release` — Освобождение блокировки

bioetl lock release --pipeline <NAME> --run-id <UUID> [--exclusive]

Внимание: Используйте только если уверены, что пайплайн не выполняется.

`lock check` — Проверка статуса блокировки

bioetl lock check --pipeline <NAME> --run-id <UUID>

`maintenance` — Maintenance операции

`maintenance vacuum` — VACUUM одной таблицы

bioetl maintenance vacuum <TABLE> [OPTIONS]

Опция	Тип	По умолчанию	Описание
`--retention-days`, `-r`	int	7	Минимальный возраст файлов
`--dry-run`	flag	False	Предпросмотр

Примеры:

bioetl maintenance vacuum chembl.activity
bioetl maintenance vacuum chembl.activity --dry-run
bioetl maintenance vacuum chembl.activity -r 30

`maintenance vacuum-all` — VACUUM всех таблиц

bioetl maintenance vacuum-all [OPTIONS]

Опция	Тип	По умолчанию	Описание
`--retention-days`, `-r`	int	7	Минимальный возраст файлов
`--dry-run`	flag	False	Предпросмотр
`--layer`	choice	`all`	Слой: `all`, `silver`, `gold`

`maintenance archive` — Архивирование таблицы

bioetl maintenance archive <TABLE> <TARGET-PATH> [--remove-source]

`maintenance bronze-cleanup` — Очистка Bronze

bioetl maintenance bronze-cleanup [OPTIONS]

Опция	Тип	По умолчанию	Описание
`--retention-days`, `-r`	int	90	Удалить файлы старше N дней
`--dry-run`	flag	False	Предпросмотр

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

Переменная	Описание	По умолчанию
`BIOETL_ENV`	Окружение (`dev`, `prod`)	`dev`
`BIOETL_DATA_DIR`	Директория данных	`./data`
`BIOETL_LOG_LEVEL`	Уровень логирования	`INFO`
`BIOETL_METRICS_ENABLED`	Включить Prometheus метрики	`true`
`BIOETL_METRICS_PORT`	Порт для Prometheus	`8000`
`BIOETL_TRACING_ENABLED`	Включить OpenTelemetry tracing	`false`

API-ключи провайдеров:

BIOETL_UNIPROT_API_KEY
BIOETL_OPENALEX_EMAIL
BIOETL_SEMANTICSCHOLAR_API_KEY

Exit Codes

Коды возврата следуют стандартам Unix (sysexits.h):

Код	Константа	Описание
0	OK	Успешное выполнение
1	FAIL	Неспецифицированная ошибка
64	EX_USAGE	Ошибка использования командной строки
65	EX_DATAERR	Ошибка формата данных
66	EX_NOINPUT	Не удалось открыть входные данные
67	EX_NOUSER	Адресат неизвестен
68	EX_NOHOST	Имя хоста неизвестно
69	EX_UNAVAILABLE	Сервис недоступен
70	EX_SOFTWARE	Внутренняя ошибка ПО
71	EX_OSERR	Ошибка ОС
72	EX_OSFILE	Отсутствует критический файл ОС
73	EX_CANTCREAT	Не удалось создать выходной файл
74	EX_IOERR	Ошибка ввода-вывода
75	EX_TEMPFAIL	Временная ошибка
76	EX_PROTOCOL	Ошибка протокола
77	EX_NOPERM	Отказано в доступе
78	EX_CONFIG	Ошибка конфигурации
80	CONFIG_ERROR	Ошибка конфигурации пайплайна
81	INIT_ERROR	Ошибка инициализации
82	PIPELINE_ERROR	Ошибка выполнения пайплайна
83	DATA_QUALITY_ERROR	Превышен DQ порог
84	LOCK_ERROR	Ошибка блокировки
85	STORAGE_ERROR	Ошибка хранилища
86	NETWORK_ERROR	Сетевая ошибка
87	CHECKPOINT_ERROR	Ошибка checkpoint
130	SIGINT	Прервано Ctrl+C
143	SIGTERM	Завершено SIGTERM

См. также

Running Pipelines — руководство по запуску
Pipeline Configuration — настройка конфигураций
Metrics & Monitoring — метрики и мониторинг
Troubleshooting — решение проблем

FilesExpand file tree

cli.md

Latest commit

History

cli.md

File metadata and controls

CLI Reference

Запуск CLI

Команды

run — Запуск одного пайплайна

run-all — Запуск всех пайплайнов провайдера

run-composite — Запуск композитных пайплайнов

adr — Работа с ADR

adr list — Список ADR

adr show — Просмотр ADR

adr validate — Валидация ADR репозитория

export — Экспорт данных

config — Управление конфигурацией

config show — Показать конфигурацию пайплайна

config validate — Валидация конфигурации

config show-settings — Глобальные настройки

config list-pipelines — Список пайплайнов

quarantine — Управление карантином

quarantine inspect — Просмотр записей

quarantine stats — Статистика

quarantine replay — Повторная обработка

quarantine purge — Удаление старых записей

quarantine resolve — Пометить как решённое

checkpoint — Управление checkpoint

checkpoint list — Список checkpoint

health — Health checks

health server — HTTP health server

health check — Проверка провайдеров

lock — Управление блокировками

lock release — Освобождение блокировки

lock check — Проверка статуса блокировки

maintenance — Maintenance операции

maintenance vacuum — VACUUM одной таблицы

maintenance vacuum-all — VACUUM всех таблиц

maintenance archive — Архивирование таблицы

maintenance bronze-cleanup — Очистка Bronze

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

Exit Codes

См. также

`run` — Запуск одного пайплайна

`run-all` — Запуск всех пайплайнов провайдера

`run-composite` — Запуск композитных пайплайнов

`adr` — Работа с ADR

`adr list` — Список ADR

`adr show` — Просмотр ADR

`adr validate` — Валидация ADR репозитория

`export` — Экспорт данных

`config` — Управление конфигурацией

`config show` — Показать конфигурацию пайплайна

`config validate` — Валидация конфигурации

`config show-settings` — Глобальные настройки

`config list-pipelines` — Список пайплайнов

`quarantine` — Управление карантином

`quarantine inspect` — Просмотр записей

`quarantine stats` — Статистика

`quarantine replay` — Повторная обработка

`quarantine purge` — Удаление старых записей

`quarantine resolve` — Пометить как решённое

`checkpoint` — Управление checkpoint

`checkpoint list` — Список checkpoint

`health` — Health checks

`health server` — HTTP health server

`health check` — Проверка провайдеров

`lock` — Управление блокировками

`lock release` — Освобождение блокировки

`lock check` — Проверка статуса блокировки

`maintenance` — Maintenance операции

`maintenance vacuum` — VACUUM одной таблицы

`maintenance vacuum-all` — VACUUM всех таблиц

`maintenance archive` — Архивирование таблицы

`maintenance bronze-cleanup` — Очистка Bronze