# Setup through the terminal

> The wizard and the full command reference: the same as on the local page, but scriptable.

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

```bash
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

```bash
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](/en/docs/connector/web-setup) running along with the agent.

## Catalogue

```bash
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

```bash
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:

```bash
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`**:

  ```bash
  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](/en/docs/connector/yaml) and put
secrets in files, and to use commands for installing integrations and checks:

```bash
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.