> For the complete documentation index, see [llms.txt](https://refkit.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://refkit.gitbook.io/docs/reference/sdk-cli-mcp.md).

# SDK, CLI, and MCP

These tools wrap the RefKit REST API. They are optional.

## JavaScript SDK

Install:

```bash
npm install @refkitnet/sdk
```

Server exports:

* `captureClick`
* `identifyCustomer`
* `reportPayment`
* `reportRefund`
* `reportDispute`

Use server capture when possible. The browser fallback is available from `@refkitnet/sdk/browser`:

```js
import { init, capture, getClickId } from "@refkitnet/sdk/browser";

init();
await capture();
const clickId = getClickId();
```

Browser capture is public and must not receive an App API key.

Managed provider backends using managed revenue keys can pass `attributionEvidence` to `identifyCustomer` for direct promotion-code attribution. Ordinary App keys must pass `clickId`. The evidence includes the applied code, Program ID, and Program Affiliate ID. Prefer `clickId` whenever one is available; RefKit never synthesizes a click for code attribution.

## CLI

Run without installing:

```bash
npx refkitnet auth login
npx refkitnet init
npx refkitnet status
```

* `auth login` signs in through device authorization.
* `init` creates or reuses credentials and prints integration steps.
* `status` reads the App setup checklist.

The CLI also manages Apps, Programs, affiliates, links, commissions, outgoing webhooks, and payouts. Link commands accept `--affiliate-id` for Developer-managed Affiliate links, and `links update` changes their labels or UTM fields. `refkitnet payouts dispatch` sends a prepared batch to an external payout system. Execution fetch and result commands require `--api-key` or `REFKIT_API_KEY` with a live key scoped to the exact App.

Every CLI help screen links back to this Help Center:

```bash
npx refkitnet --help
npx refkitnet apps --help
```

## RefKit MCP

The MCP server lets supported agents inspect and manage RefKit through tools.

First sign in:

```bash
npx refkitnet auth login
```

Then add the server to the agent's MCP configuration:

```json
{
  "mcpServers": {
    "refkit": {
      "command": "npx",
      "args": ["-y", "@refkitnet/mcp"]
    }
  }
}
```

The MCP uses the CLI session stored in `~/.refkitnet/config.json`. Affiliate tools can instead use `REFKIT_AFFILIATE_KEY` with an `rk_aff_*` key.

Set `REFKIT_API_KEY` to an App-scoped Test or Live key for `report_payment`, `report_refund`, and `report_dispute`. The same variable must contain a live key for payout execution tools.

Developer-managed Affiliate link tools are `list_owned_affiliate_links`, `create_owned_affiliate_link`, `update_owned_affiliate_link`, and `delete_owned_affiliate_link`.

With the default Cloud origin, `get_help` returns the matching RefKit Help Center URL. With a custom origin, it returns operator-documentation guidance and no RefKit Cloud URL.

Common agent workflow:

1. Check authentication.
2. Call `get_help` with the closest topic and open the returned Help Center page.
3. Create or inspect App credentials.
4. Implement the REST integration in the Customer App.
5. Read setup status to verify the flow.

Keep implementation details in the Customer App's codebase. Use MCP for RefKit resources and status, not as a replacement for the runtime integration.