Connectors

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.

Connector types

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.

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

Credential resolution

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

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.

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.

API routes

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

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.

Config examples

{
  "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

Source anchors