# Настройка через терминал

> Мастер и полный справочник команд: то же самое, что на локальной странице, но скриптуемо.

Коннектор на сервере без графики — обычный случай, а не исключение, поэтому
командная строка равноправна. **Нет настройки, доступной только со страницы, и нет
настройки, доступной только из терминала**: обе правят один файл, под одной проверкой.

## Мастер первой настройки

```bash
connector setup --config /etc/connector/connector.yaml --cli
```

Те же шаги, что и на странице, по порядку:

1. **Адрес relay** (предзаполнен — Enter) и **каталог состояния**.
2. **Провайдер** — тип, адрес, токен. Агент сразу проверит доступ и **выведет список
   репозиториев**, которые видит.
3. **Выбор репозиториев** — номера через запятую (`1,3`) или `all`.
4. Ещё один провайдер или завершить (пустой ввод).
5. **Код привязки** из приложения Buff — можно пропустить и привязать позже.

```
Провайдер (…): gitea
Base URL: https://gitea.corp.local
Токен доступа: ********
   1) team/backend (private)
   2) team/frontend
   3) team/docs
Выберите репозитории (напр. 1,3 или all): 1,2
  добавлено: gitea (2 репо)
```

Токен сохраняется в файл с правами `600` в каталоге состояния и к нам не уходит.

## Привязка и запуск

```bash
connector pair --config /etc/connector/connector.yaml --code bufc_… [--label «Сервер сборки»]
connector run  --config /etc/connector/connector.yaml
```

`--label` — как агент будет называться в приложении; по умолчанию берётся имя хоста.
Добавьте `--admin 127.0.0.1:8765`, чтобы вместе с агентом работала
[локальная страница](/docs/connector/web-setup).

## Каталог

```bash
connector catalog --config /etc/connector/connector.yaml            # что можно поставить
connector catalog show github --config /etc/connector/connector.yaml # границы доступа версии
connector install github --config /etc/connector/connector.yaml      # последняя совместимая
connector install github@1.0.0 --config /etc/connector/connector.yaml # конкретная версия
```

`catalog show` печатает то же, что видно в карточке на странице: по каким полям
выводятся разрешённые адреса, какие учётные данные нужны, принимает ли интеграция
вебхуки и какие у неё инструменты — с пометкой, какие только читают. Если каталог
недоступен, команда честно скажет об этом и покажет последний прочитанный.

`install` без версии ставит **последнюю совместимую с этой сборкой** агента, а не
просто последнюю: интеграция, которой нужен более новый коннектор, ставиться не будет.

## Подключения

```bash
connector instance list --config …                 # что настроено
connector instance show <id|слаг> --config …       # одно подключение (секреты скрыты)
connector instance set  <id|слаг> --config … …     # создать или изменить
connector instance secret <id|слаг> --secret api --config …   # секрет со стандартного ввода
connector instance enable|disable <id|слаг> --config …
connector instance rm <id|слаг> --config … [--dry-run]
connector instance check <id|слаг>                 # проверка связи у работающего агента
connector instance log   <id|слаг>                 # журнал подключения
```

Создать подключение целиком:

```bash
connector instance set --config /etc/connector/connector.yaml \
  --plugin github --version 1.0.0 \
  --alias "GitHub клиента" --dev-project backend \
  --set base_url=https://api.github.com \
  --set repos=acme/api,acme/web \
  --set mention_alias=buff

# секрет — отдельной командой, со стандартного ввода
connector instance secret github --secret api \
  --config /etc/connector/connector.yaml < /run/secrets/github-token
```

Что стоит знать про эти команды:

- **`--set key=value` проверяется по схеме интеграции.** Списки пишутся через запятую
  (`repos=a/b,c/d`), числа и флаги приводятся к типу. Ключ, которого в схеме нет, или
  значение, которое ей не подходит, — ошибка, а не молча сохранённая строка.
- **`--dry-run`** показывает, что изменится, и ничего не пишет.
- **Секрет вводится с потока ввода**, не аргументом: аргумент попал бы в историю
  оболочки и в список процессов. Для трекера, который входит парой,
  добавьте **`--account`**:

  ```bash
  connector instance secret jira --secret api --account bot@example.com \
    --config /etc/connector/connector.yaml < /run/secrets/jira-token
  ```

  Вид доступа (bearer, basic или собственный заголовок трекера) берётся из манифеста
  интеграции — команда печатает, какой применён.
- **`check` и `log` ходят к работающему агенту** на его локальный адрес
  (`--addr`, по умолчанию `127.0.0.1:8765`), потому что это состояние живого процесса,
  а не файла.
- **Ссылка (`<id|слаг>`)** — либо GUID подключения, либо его слаг (короткое имя,
  которое коннектор выводит из названия). Слаг же попадает в имена инструментов,
  которые видит модель.

## Автоматизация

Для Ansible и CI обычно проще писать [конфиг напрямую](/docs/connector/yaml) и класть
секреты в файлы, а командами пользоваться для установки интеграций и проверок:

```bash
connector install github --config /etc/connector/connector.yaml
connector instance check github --addr 127.0.0.1:8765
```

Агент следит за файлом конфига: правки применяются на лету, перезапуск не нужен.