Setup through the terminal

A connector on a server without graphics is the usual case, not an exception, so the command line is on an equal footing. There is no setting available only from the page and no setting available only from the terminal: both edit one file, under one check.

The first-time setup wizard

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

The same steps as on the page, in order:

1. The relay address (prefilled — Enter) and the state directory.
2. Provider — type, address, token. The agent checks access right away and lists the repositories it sees.
3. Choosing repositories — numbers separated by commas (1,3) or all.
4. One more provider, or finish (empty input).
5. The pairing code from the Buff app — you can skip it and pair later.

The wizard speaks Russian; a session looks like this (provider, base URL, access token, then the repository choice):

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

The token is saved to a file with 600 permissions in the state directory and does not reach us.

Pairing and running

connector pair --config /etc/connector/connector.yaml --code bufc_… [--label "Build server"]
connector run  --config /etc/connector/connector.yaml

--label — what the agent is called in the app; the host name by default. Add --admin 127.0.0.1:8765 to have the local page running along with the agent.

Catalogue

connector catalog --config /etc/connector/connector.yaml            # what can be installed
connector catalog show github --config /etc/connector/connector.yaml # a version's access boundaries
connector install github --config /etc/connector/connector.yaml      # the latest compatible one
connector install github@1.0.0 --config /etc/connector/connector.yaml # a specific version

catalog show prints the same as the card on the page: which fields the allowed addresses are derived from, which credentials are needed, whether the integration accepts webhooks and what tools it has — marking which ones only read. If the catalogue is unavailable, the command says so honestly and shows the last one it read.

install without a version installs the latest one compatible with this build of the agent, not simply the latest: an integration that needs a newer connector will not be installed.

Connections

connector instance list --config …                 # what is configured
connector instance show <id|slug> --config …       # one connection (secrets hidden)
connector instance set  <id|slug> --config … …     # create or change
connector instance secret <id|slug> --secret api --config …   # a secret from standard input
connector instance enable|disable <id|slug> --config …
connector instance rm <id|slug> --config … [--dry-run]
connector instance check <id|slug>                 # connectivity check on the running agent
connector instance log   <id|slug>                 # the connection's log

Creating a whole connection:

connector instance set --config /etc/connector/connector.yaml \
  --plugin github --version 1.0.0 \
  --alias "Client GitHub" --dev-project backend \
  --set base_url=https://api.github.com \
  --set repos=acme/api,acme/web \
  --set mention_alias=buff

# the secret — with a separate command, from standard input
connector instance secret github --secret api \
  --config /etc/connector/connector.yaml < /run/secrets/github-token

Worth knowing about these commands:

• --set key=value is checked against the integration’s schema. Lists are comma-separated (repos=a/b,c/d), numbers and flags are converted to their type. A key that is not in the schema, or a value that does not fit it, is an error, not a silently saved string.

• --dry-run shows what will change and writes nothing — and checks the same things a write would, including the length limit of the notes.

• Notes for the AI are set with --ai-notes "text" or from a file with --ai-notes-file notes.md (- — from standard input). The 2048-character limit is lifted only with an explicit --ai-notes-unbounded true: the warning the page shows is not here, so you have to spell it out. A flag that was not given changes nothing — --alias does not erase saved notes.

• A secret is entered from the input stream, not as an argument: an argument would end up in the shell history and in the process list. For a tracker that signs in with a pair, add --account:

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

  The kind of access (bearer, basic or the tracker’s own header) is taken from the integration’s manifest — the command prints which one was applied. Where an integration offers several kinds (Google Drive: a service account or your own account), the choice is named with the --kind service_account / --kind oauth2 flag; the value for oauth2 is the JSON of your own OAuth client {"client_id":"…","client_secret":"…"}.

• signin signs in with your own account for credentials of the oauth2 kind: connector instance signin <id|slug> --secret api prints the sign-in address — open it in any browser — and after consent waits for the address of the page the source returned to (or the code from it). The refresh token goes into the credentials file, and from then on the connector refreshes access itself. The command talks to the running agent, like check.

• check and log talk to the running agent on its local address (--addr, 127.0.0.1:8765 by default), because this is the state of a live process, not of a file.

• The reference (<id|slug>) is either the connection’s GUID or its slug (the short name the connector derives from the name). The slug also goes into the names of the tools the model sees.

Automation

For Ansible and CI it is usually simpler to write the config directly and put secrets in files, and to use commands for installing integrations and checks:

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

The agent watches the config file: edits apply on the fly, no restart is needed.