# Connectors

How nikcli connects external services, stores credentials, exposes connector tools, and receives bot webhooks.

## Overview

Connectors are service-specific integrations configured under `connectors` in `nikcli.json`. The runtime lives in `packages/nikcli/src/connectors`. It checks credentials, runs health checks, creates AI SDK tools for services with operations, exposes prompts, and caches status/tool results.

Agent

### Tool connectors

Figma, Slack, GitHub, and Lovable expose operations as dynamic agent tools.

Webhook

### Bot connectors

Discord, Teams, Google Chat, Linear, GitHub, and Slack are also used by chatbot webhook routes.

Secrets

### Credential store

Saved connector credentials are written to `Global.Path.data/connectors-auth.json` with `0600` on Unix.

Resolution

### Config first, auth second

Environment flags win, then inline config credentials, then saved connector auth records.

## Connector types

| Type | Credential | Health check | Agent tools |
| --- | --- | --- | --- |
| `figma` | Personal access token | `FigmaApi.getMe` | File, components, styles, comments. |
| `slack` | Bot token | `SlackApi.listUsers` | List channels, send message, search, channel info, thread reply. |
| `github` | Personal access token | `GithubApi.getUser` | Repo, file, issue, issue list, code search, repo list. |
| `lovable` | Token or API key | `LovableApi.getProjects` | Projects, project, chats, send message, files, run prompt. |
| `discord` | Bot token | No-op health check | No connector tools; bot/webhook use. |
| `teams` | Bot token | No-op health check | No connector tools; bot/webhook use. |
| `gchat` | Bot token | No-op health check | No connector tools; bot/webhook use. |
| `linear` | Bot token | No-op health check | No connector tools; bot/webhook use. |

## Add and authenticate

`nikcli connectors add` patches either the current project config or global config. If you provide a credential during the wizard, it writes the credential to the connector auth store, not into the config file. `auth` and `logout` manage that store.

Terminal

bash 

```
nikcli connectors add
nikcli connectors list
nikcli connectors auth github
nikcli connectors logout github
```

$ shell · paste into your terminal

| Command | Behavior |
| --- | --- |
| `connectors add` | Select scope, name, type, enabled state, optional credential. |
| `connectors list` | Show configured connector status and saved credential hint. |
| `connectors auth [name]` | Save a token, bot token, or API key for the selected connector. |
| `connectors logout [name]` | Remove saved credentials from `connectors-auth.json`. |

## Credential resolution

`resolveCredential` uses a strict order: environment flag, config inline credential, saved auth record, then no credential.

| Type | Env flag | Config field | Saved field |
| --- | --- | --- | --- |
| `figma` | `NIKCLI_FIGMA_TOKEN` | `token` | `token` |
| `github` | `NIKCLI_GITHUB_TOKEN` | `token` | `token` |
| `slack` | `NIKCLI_SLACK_BOT_TOKEN` | `botToken` | `botToken` |
| `lovable` | `NIKCLI_LOVABLE_TOKEN` or `NIKCLI_LOVABLE_API_KEY` | `token` or `apiKey` | `token` or `apiKey` |

Inline config credentials are supported but not preferred

The CLI wizard stores credentials separately so project config can be shared without tokens. Use inline credentials only when you intentionally want config-managed secrets.

## Tool operations

Tool-capable connectors generate names by prefixing the configured connector name and operation name. For a connector named `github`, operation `github_get_repo` becomes `github_github_get_repo`.

| Connector | Operations |
| --- | --- |
| Figma | `figma_get_file`, `figma_get_components`, `figma_get_styles`, `figma_get_comments`. |
| Slack | `slack_list_channels`, `slack_send_message`, `slack_search_messages`, `slack_get_channel_info`, `slack_reply_to_thread`. |
| GitHub | `github_get_repo`, `github_get_file`, `github_create_issue`, `github_list_issues`, `github_search_code`, `github_list_repos`. |
| Lovable | `lovable_get_projects`, `lovable_get_project`, `lovable_get_chats`, `lovable_send_message`, `lovable_get_project_files`, `lovable_run_prompt`. |

Each operation is wrapped as a dynamic tool with a JSON schema built from the operation args. Results are returned as strings or pretty JSON.

## Bot connectors

Bot/webhook platforms are mounted under `/chatbot`. The route file exposes webhook handlers for Discord, Slack, Teams, Google Chat, Linear, and GitHub. These are separate from connector tool operations even when they share the same service name.

| Webhook route | Platform |
| --- | --- |
| `POST /chatbot/discord/:name` | Discord |
| `POST /chatbot/slack/:name` | Slack |
| `POST /chatbot/teams/:name` | Microsoft Teams |
| `POST /chatbot/gchat/:name` | Google Chat |
| `POST /chatbot/linear/:name` | Linear |
| `POST /chatbot/github/:name` | GitHub |

## API routes

| Route | Behavior |
| --- | --- |
| `GET /connectors/status` | Return status for configured connectors. |
| `POST /connectors/:name/auth` | Set token, bot token, or API key for a connector. |
| `DELETE /connectors/:name/auth` | Remove connector auth entry. |
| `POST /connectors/:name/invalidate` | Invalidate cached status/tools for one connector. |

Terminal

bash 

```
curl http://127.0.0.1:4096/connectors/status

curl -X POST http://127.0.0.1:4096/connectors/github/auth \
  -H "Content-Type: application/json" \
  -d '{"token":"ghp_example"}'

curl -X POST http://127.0.0.1:4096/connectors/github/invalidate
```

$ shell · paste into your terminal

## Caches and invalidation

Connector status and tool creation are cached based on the active config. Auth writes, removals, and explicit invalidation should clear the relevant cache so the next list/tool call rechecks credentials and health.

| Cache | Invalidated by |
| --- | --- |
| Status | `invalidateStatusCache` and connector invalidation. |
| Tools | `invalidateToolsCache` and connector invalidation. |
| One connector | `invalidateConnectorCache(name)`. |

## Config examples

connectors config

json 

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

```
{
  "connectors": {
    "github": {
      "type": "github",
      "enabled": true
    },
    "figma-design": {
      "type": "figma",
      "enabled": true
    },
    "slack-builds": {
      "type": "slack",
      "enabled": true
    },
    "linear-bot": {
      "type": "linear",
      "enabled": true
    }
  }
}
```

Use distinct names when the same service is used for different contexts, such as `slack-builds` and `slack-support`. Tool names include the connector name, so a descriptive name helps the model choose the correct integration.

## Failure modes

| Symptom | Likely cause | Fix |
| --- | --- | --- |
| `needs_auth` | No env, config, or saved credential resolved. | Run `nikcli connectors auth <name>` or set the provider env flag. |
| `failed` | Health check failed or connector type is unknown. | Check token scope and service API response. |
| Tools missing | Connector disabled, not authenticated, or type has no operations. | Check status and remember bot-only connectors have no agent tools. |
| Old credential still used | Status/tool cache was not invalidated after credential change. | Invalidate connector or restart the process. |
| Lovable token ignored | Credential stored as API key but type resolution expected token. | Lovable supports token fallback to API key; verify saved field and config field. |

## Source anchors

| Need | File |
| --- | --- |
| Connector service | `packages/nikcli/src/connectors/index.ts` |
| Connector registry and tools | `packages/nikcli/src/connectors/registry.ts` |
| Credential resolution | `packages/nikcli/src/connectors/credentials.ts` |
| Credential store | `packages/nikcli/src/connectors/auth.ts` |
| CLI command | `packages/nikcli/src/cli/cmd/connectors.ts` |
| Server routes | `packages/nikcli/src/server/httpapi/connectors.ts` |
| Chatbot routes | `packages/nikcli/src/server/httpapi/chatbot.ts` |
| Service APIs | `packages/nikcli/src/connectors/api` |

---

Source: https://nikcli-ai.dev/docs/connectors