# talkbar-cli

Операции TalkBar из терминала и скриптов с talkbar-cli — той же программой, что обслуживает MCP: команды, параметры, ввод, вывод и коды завершения.

Canonical URL: https://docs.talkbar.ru/mcp/cli


`talkbar-cli` — программа командной строки, которая поставляется вместе с TalkBar. Она выполняет те же операции, что и ИИ-ассистент через MCP, — из терминала, скрипта или ИИ-агента, который умеет запускать команды. Кроме того, она запускает MCP-сервер и выполняет экспорт в фоне.

## Перед началом

- `talkbar-cli` поставляется вместе с TalkBar. Где именно — показано в поле **Настройки → Доступ по MCP → Путь к исполняемому файлу**. Кнопка **Добавить в PATH** там же позволяет запускать программу по имени из любого терминала. См. [Где установлен talkbar-cli](/mcp/setup#где-установлен-talkbar-cli).
- Программа открывает папку данных TalkBar или папку из `TALKBAR_DATA_ROOT`, если эта переменная задана. Фактический путь указан в **Настройки → Доступ по MCP → Папка данных**. Приложение может быть как открыто, так и закрыто.
- Программа выполняет то, что вы ввели, от вашего имени. Переключатели раздела «Доступ по MCP» на неё не действуют, а правила администратора и лимиты тарифа — действуют. См. [Что игнорирует командная строка](/mcp/access-and-permissions#что-игнорирует-командная-строка).

```shell
talkbar-cli --version
talkbar-cli --help
talkbar-cli tools --help
```

В примерах используются оболочка POSIX в macOS или PowerShell в Windows. Если оболочка иначе обрабатывает кавычки в JSON, используйте `--args-file`.

## Команды

| Команда | Что делает |
| --- | --- |
| `tools list [--compact]` | Выводит список операций. |
| `tools info <id>` | Показывает одну операцию: что она делает, её переключатель MCP по умолчанию и аргументы. |
| `tools call <id> [--args <json> \| --args - \| --args-file <path>]` | Выполняет одну операцию и выводит результат в JSON. |
| `tools batch [--file <path>] [--stop-on-error]` | Выполняет много операций в одном процессе и выводит результаты одним массивом JSON. |
| `search <words>…` | Ищет по рабочему пространству так же, как поиск в приложении. |
| `serve [--transport stdio]` | Запускает MCP-сервер. Эту команду за вас выполняет ИИ-приложение. |
| `exports run`, `exports worker`, `exports notion connect` | Доставляет экспорт из очереди и подключает Notion. См. [Экспорт](#экспорт). |

`talkbar-cli call …` (без `tools`) — ошибка использования, в ответ на которую предлагается `talkbar-cli tools call`.

## Глобальные параметры

Эти параметры можно указывать до или после команды:

| Параметр | Что делает | По умолчанию |
| --- | --- | --- |
| `--output json` | Выводит JSON вместо таблицы для `tools list`, `tools info` и `search`, а ошибки — в виде JSON на стандартный вывод. `tools call` и `tools batch` всегда выводят JSON. | `table` |
| `--db <path>` | Открывает указанный файл базы данных TalkBar вместо папки данных. Файл должен уже существовать и быть базой данных TalkBar; неверный путь отклоняется, файл никогда не создаётся. | База данных в папке данных |
| `-v`, `--verbose` | Выводит внутренние события TalkBar в стандартный поток ошибок в виде строк JSON. Если команда не вызывает событий, ничего лишнего не выводится. | Выключено |

## Список и описание операций

```shell
talkbar-cli tools list
talkbar-cli tools list --compact
talkbar-cli tools info notes.create
talkbar-cli --output json tools info notes.create
```

- `tools list` выводит таблицу с идентификатором, видом (`read` или `mutation`), категорией и описанием, а затем общее количество. С `--output json` для каждой операции выводятся заголовок, описание, категория, вид, переключатель MCP по умолчанию и полная схема входных данных.
- `tools list --compact` выводит по одной строке на операцию: идентификатор, вид (`read` или `change`) и краткое описание, разделённые табуляцией. Это самый экономный указатель для скриптов и ИИ-агентов.
- `tools info <id>` выводит описание операции, включена ли она по умолчанию в MCP, строку использования и принимаемые аргументы в виде JSON Schema. Аргументы — JSON в camelCase.

В список входят все операции, которые не заблокировал администратор. Аргументы и результаты каждой операции описаны в [справочнике операций](/mcp/operations).

## Запуск одной операции

Передайте аргументы в виде объекта JSON:

```shell
talkbar-cli tools call sessions.list --args '{"limit":5}'
talkbar-cli tools call notes.get --args '{"noteId":"note-k2v9w8x7c6b5n4m3l2j1h0g9"}'
```

`workspaceId`, как и в MCP, необязателен: без него используется пространство, открытое в приложении.

### Аргументы из стандартного ввода или файла

Длинный текст, например текст заметки, удобнее передавать через стандартный ввод или файл, чем в командной строке:

| Форма | Откуда читаются аргументы |
| --- | --- |
| `--args '<json>'` | Из командной строки. По умолчанию `{}`. |
| `--args -` | Из стандартного ввода |
| `--args-file <path>` | Из файла. `--args-file -` тоже означает стандартный ввод. |


### Windows

```powershell
Get-Content note.json -Raw | talkbar-cli tools call notes.create --args -
```
### macOS

```shell
cat note.json | talkbar-cli tools call notes.create --args -
```


```shell
talkbar-cli tools call notes.create --args-file note.json
```

```json [note.json]
{
  "title": "Weekly sync follow-ups",
  "markdown": "## Follow-ups\n\n- Send the revised quote to Dana\n- Book the next sync"
}
```

Файлы и переданный по конвейеру текст, сохранённые с меткой порядка байтов UTF-8 (так их записывает Windows PowerShell 5), читаются правильно.


PowerShell и `cmd` по-разному обрабатывают кавычки в JSON. Если `--args '{...}'` выдаёт «Invalid JSON arguments», поместите JSON в файл и используйте `--args-file`.


## Запуск пакета

`tools batch` выполняет много операций в одном процессе, по порядку. Это быстрее, чем отдельная команда на каждую операцию, а открытое приложение обновляется один раз для всех.

```shell
'[{"tool":"notes.list","args":{"limit":3}},{"tool":"sessions.list","args":{"limit":5}}]' | talkbar-cli tools batch
talkbar-cli tools batch --file calls.json --stop-on-error
```

- На вход подаётся массив JSON из `{"tool", "args"}` или форма MCP `{"calls": [...], "stopOnError": true}`. Данные берутся из `--file` или из стандартного ввода, если `--file` не указан или равен `-`.
- Ограничения в 20 операций, как в MCP, нет. На `[]` выводится `[]`.
- `--stop-on-error` (или `"stopOnError": true`) останавливает выполнение на первой неудачной операции.
- Результат всегда выводится одним массивом JSON, по одной записи на каждую выполненную операцию:

```json
[
  { "tool": "notes.list", "ok": true, "result": { "items": [], "nextCursor": null, "hasMore": false, "totalCount": 0 } },
  { "tool": "sessions.get", "ok": false, "error": { "code": "not_found", "message": "Session not found in workspace" } }
]
```

Если хотя бы одна операция завершилась неудачей, команда, выведя все результаты, завершается с кодом 1. В стандартный поток ошибок при этом выводится, сколько операций не удалось, например `1 of 2 operations failed`.

## Поиск

`search` — это универсальный поиск приложения в терминале, включая фрагменты транскриптов:

```shell
talkbar-cli search pricing review
talkbar-cli search "renewal date" --kinds session,note --limit 10
talkbar-cli search budget --match any --output json
```

| Параметр | Что делает | По умолчанию |
| --- | --- | --- |
| `--workspace <id>` | Ищет в этом пространстве | Пространство, открытое в приложении |
| `--project <id>` | Только элементы из этого проекта | Все проекты |
| `--kinds <list>` | Через запятую: `session`, `note`, `chat`, `action_item`, `document`, `memory`, `person`, `company`, `project`, `series` | Все виды |
| `--limit <n>` | Максимум результатов, от 1 до 100 | 20 |
| `--match all\|any` | `all`: должно совпасть каждое слово. `any`: слова воспринимаются как просьба на естественном языке. | `all` |
| `--include-archived` | Находит также архивированные серии, людей, компании и карточки знаний | Выключено |

В табличном выводе совпадения сгруппированы по видам, у каждого — название, фрагмент и ссылка в приложении. `--output json` выводит тот же объект, что и [`talkbar_find`](/mcp/tools#talkbar_find).


`search` по умолчанию требует совпадения каждого слова, как строка поиска в приложении. `talkbar_find` в MCP по умолчанию использует `any`.


## Запуск MCP-сервера

```shell
talkbar-cli serve --transport stdio
```

Запускает MCP-сервер на стандартном вводе и выводе. `stdio` — единственный транспорт и он же используется по умолчанию. ИИ-приложение само выполняет эту команду с заданной `TALKBAR_DATA_ROOT`; см. [Настройка MCP](/mcp/setup). В отличие от остальных команд, `serve` подчиняется всем переключателям в разделе **Настройки → Доступ по MCP**. `--output` на неё не влияет.

## Экспорт

Команда `exports` доставляет экспорт из очереди — то же, что делает приложение, пока оно запущено. Сначала настройте места экспорта в приложении; см. [Экспорт](/sharing/exports).

```shell
talkbar-cli exports run --workspace WORKSPACE_ID --batch BATCH_ID --wait
talkbar-cli exports worker
talkbar-cli exports worker --drain
```

| Команда | Что делает |
| --- | --- |
| `exports run --workspace <id> --batch <id>` | Выполняет один проход указанного пакета экспорта, затем выводит состояние пакета в JSON. |
| `… --wait` | Продолжает, пока какая-либо доставка в пакете запланирована или выполняется. |
| `… --timeout <seconds>` | Вместе с `--wait`: прекращает ожидание через указанное число секунд и завершается с кодом 1. По умолчанию 600. |
| `exports worker` | Выполняет автоматический и другой экспорт по мере наступления срока, пока вы не остановите его с помощью `Ctrl+C`. |
| `exports worker --drain` | Выполняет экспорт, срок которого уже наступил, и завершается. |
| `exports notion connect --workspace <id> --destination <id>` | Читает токен Notion со стандартного ввода и сохраняет его в зашифрованном виде для этого места экспорта Notion. |

Командам `exports` нужен `--workspace` (его можно узнать с помощью `tools call workspace.list`). `exports notion connect` не читает токен с клавиатуры, чтобы он никогда не появлялся на экране; передайте его по конвейеру из менеджера паролей:


### Windows

```powershell
Get-Secret -Name TalkBarNotionToken -AsPlainText | talkbar-cli exports notion connect --workspace WORKSPACE_ID --destination DESTINATION_ID
```
### macOS

Передайте токен из менеджера паролей через конвейер в `talkbar-cli exports notion connect --workspace WORKSPACE_ID --destination DESTINATION_ID`.


Чтобы сначала поставить экспорт в очередь, используйте `tools call exports.enqueue`. См. [Экспортировать сессию](/mcp/examples#экспортировать-сессию).

## Вывод и ошибки

- **В стандартный вывод попадают только результаты.** Результаты выводятся в JSON: с отступами в терминале и компактно, если вывод передаётся другой программе или ИИ-агенту.
- **Ошибки выводятся в стандартный поток ошибок** строкой, начинающейся с `Error:`. При неверном аргументе дополнительно предлагается `tools info <id>`, при неизвестной операции — `tools list`.
- **С `--output json`** неудачная команда также выводит ошибку на стандартный вывод — в том же формате, что использует MCP:

```json
{"error":{"code":"not_found","message":"Note not found in workspace"}}
```

`tools call` выводит собственный код операции (`not_found`, `invalid_arguments`, `plan_limit` и так далее); при других ошибках, например при неверном пути в `--db` или правиле администратора, выводится `"code": "failed"`. `tools batch` выводит только массив результатов. Читайте стандартный вывод отдельно и не объединяйте с ним стандартный поток ошибок (`2>&1`).

### Коды завершения

| Код | Значение |
| --- | --- |
| `0` | Выполнено |
| `1` | Отклонено или завершилось ошибкой. Для `tools batch` — хотя бы одна операция завершилась неудачей. |
| `2` | Ошибка использования: неизвестная команда или параметр либо отсутствующий аргумент |

## Для ИИ-агентов с доступом к командной строке

Агент, который умеет запускать команды, например Claude Code или Codex, может использовать `talkbar-cli` вместо MCP. Это не требует определений инструментов, а одна команда может выполнить много операций.

- Получайте указатель с помощью `talkbar-cli tools list --compact`, а аргументы одной операции — с помощью `talkbar-cli tools info <id>`.
- Используйте пакеты вместо циклов: один `tools batch` заменяет много запусков `tools call`, а каждый запуск `talkbar-cli` требует времени на старт.
- Передавайте длинный текст через `--args -` или `--args-file`.
- Ориентируйтесь на коды ошибок из `--output json`, а не на текст сообщений.
- Помните, что командная строка игнорирует переключатели раздела «Доступ по MCP». Давайте агенту этот способ, только если вы готовы к тому, что он сможет выполнить любую операцию, которую могли бы выполнить вы сами.

## Приложение обновляется само

После успешного изменения `talkbar-cli` (и MCP-сервер) сообщает запущенному приложению TalkBar, что изменилось, по закрытому локальному каналу. Приложение обновляет экраны и меню в трее, где показаны эти элементы. Если приложение закрыто, ничего не отправляется и ничего не замедляется.

## См. также

- [Обзор MCP](/mcp/overview)
- [Доступ и разрешения](/mcp/access-and-permissions)
- [Ошибки и ограничения](/mcp/errors-and-limits)
- [Примеры](/mcp/examples)
- [Справочник операций](/mcp/operations)