# catalib logs

Логи устройства (`adb logcat`), отфильтрованные по текущему плагину. Быстрый ответ на «что плагин пишет в лог».

```bash
catalib logs [--project DIR] [--serial S] [--lines N] [--clear] [--all] [--filter TEXT] [--adb|--no-adb]
```

## Опции

| Опция                | По умолчанию | Назначение                                    |
| -------------------- | ------------ | --------------------------------------------- |
| `--project`, `-p`    | `.`          | каталог проекта (откуда берётся `plugin_id`)  |
| `--serial`           | —            | серийный номер устройства (если их несколько) |
| `--lines`, `-n`      | `100`        | сколько последних строк logcat читать         |
| `--clear`            | выкл.        | очистить буфер логов перед чтением            |
| `--all`              | выкл.        | не фильтровать — весь logcat                  |
| `--filter`           | `plugin_id`  | своя подстрока фильтра вместо `plugin_id`     |
| `--adb` / `--no-adb` | авто         | через `adb` или системный `logcat` напрямую   |

## Поведение

1. Читает `logcat -d -t <lines>` (при `--clear` сначала `logcat -c`). На ПК — через `adb`; на самом устройстве (Termux/Pydroid) — системный `logcat` напрямую (`adb` там не нужен; авто, override `--adb/--no-adb`).
2. Фильтр-подстрока: `--filter` → её, иначе `plugin_id` из `catalib.toml`, при `--all` — без фильтра. Сравнение регистронезависимое (плагины логируют как `[plugin_id] ...`).
3. Если по фильтру ничего не найдено — печатает подсказку и «хвост» последних строк (видно, что устройство вообще пишет).

Команда и логика совпадают с инструментом MCP `adb_get_logs` — единый опыт независимо от того, чем пользуетесь.

## Код возврата

| Код | Когда                                                                             |
| --- | --------------------------------------------------------------------------------- |
| `0` | логи получены (даже если по фильтру пусто)                                        |
| `1` | ошибка `adb`/`logcat` (нет в PATH, устройство не отвечает, `subprocess` запрещён) |

Нет валидного `catalib.toml` и не задан `--filter`/`--all` — выводится весь logcat с предупреждением в stderr (код `0`).

## Пример

```bash
$ catalib logs -n 500
[demo] плагин загружен
[demo] хук .hello: ответ отправлен

$ catalib logs --all -n 50          # весь хвост, без фильтра
$ catalib logs --filter "Exception" # только строки с Exception
$ catalib logs --clear -n 200       # очистить и смотреть «с чистого листа»
```

## На самом устройстве (Termux/Pydroid)

`logs` работает и на устройстве (системный `logcat` напрямую), но **чужой** logcat (то, что пишет exteraGram) Android отдаёт только с разрешением `READ_LOGS`. Без него обычное приложение Termux/Pydroid видит лишь свои строки. При отказе `logs` честно сообщает об этом и подсказывает варианты: root, Shizuku или единоразовый `pm grant ... android.permission.READ_LOGS` через adb-grant. На Pydroid вдобавок может быть запрещён `subprocess`. Подробнее — [Разработка на устройстве](/catalib/rukovodstvo/android.md).

## Если логов нет

В некоторых сборках exteraGram логи плагина не доходят до `logcat`. Тогда пишите диагностику в файл в каталоге плагина (см. [Подводные камни](/catalib/reshenie-problem/troubleshooting.md)) и смотрите его через [`catalib`-доступ к файлам](/catalib/rukovodstvo/sdk-access.md). Проверить готовность окружения в целом — [`catalib doctor`](/catalib/cli/doctor.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://raito-kyokai.gitbook.io/catalib/cli/logs.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.