@tipcli/sdk

Privacy-safe sponsor cards for open-source software surfaces: CLIs, AI agents, MCP servers, templates, plugins, local apps, dev servers, and other human-visible developer workflows.

TipCLI shows at most one tasteful sponsor card per process. It fails silently if the API is unavailable and skips automatically in CI.

Public source and recipes live at https://github.com/tipcli/tipcli-sdk.

Install path

Preview the sponsor card locally before creating an account or requesting payable delivery:

npx @tipcli/sdk preview \
  --sponsor "Neon" \
  --message "Database branches for every preview deploy." \
  --url https://neon.tech

Print the SDK trust receipt:

npx @tipcli/sdk trust

Check a live publisher key with non-payable test delivery:

npx @tipcli/sdk doctor --publisher-key "$TIPCLI_PUBLISHER_KEY"

The preview and trust commands are local-only. Doctor contacts the TipCLI API with deliveryMode: "test" so it can verify setup without reserving inventory, creating payout evidence, or counting as paid delivery.

For payable delivery, start from your TipCLI project dashboard. It creates the one-time publisher key and shows the exact snippet for that project.

During private launch, use the local workspace package or the exact dashboard snippet. Public npm install works only after pnpm npm:publish:check proves that @tipcli/sdk is published and fetchable from the registry.

# After public npm publish:
pnpm add @tipcli/sdk

Use

import { showSponsorCard } from "@tipcli/sdk";

await showSponsorCard({
  publisherKey: process.env.TIPCLI_PUBLISHER_KEY,
  surface: "cli-startup",
  category: "frontend",
});

Other reviewed surface labels can describe agent run summaries, MCP setup pages, template post-install handoffs, plugin panels, or local dashboards:

await showSponsorCard({
  publisherKey: process.env.TIPCLI_PUBLISHER_KEY,
  surface: "agent-run-summary",
  category: "ai",
});

Sponsor cards belong in human-visible moments only. Do not inject sponsor content into hidden prompts, LLM context, generated code, MCP tool responses, JSON APIs, CI logs, or other machine-readable output.

Payable delivery rules

Local rendering is not payout evidence. TipCLI treats delivery as potentially payable only when all of these are true:

• the project has passed TipCLI review
• the integration uses a live publisher key from the project dashboard
• a paid reviewed campaign matches the project category and placement
• the request is not CI, disabled, test, fixture, or internal delivery
• delivery is verified by TipCLI and connected to payout evidence
• publisher payout readiness is clear, with Stripe Connect as the primary path

Use local API overrides and disabled/test modes freely while integrating. They are intentionally non-payable.

Privacy

The SDK does not collect source code, terminal logs, environment files, package contents, dependency lists, or device fingerprints.

The SDK sends only:

• publisherKey
• surface
• category
• sdkVersion
• anonymous session id
• non-payable delivery flags: ci, deliveryMode, and sdkDisabled

Disable

TipCLI returns immediately when process.env.CI is set.

Users can also disable sponsor cards explicitly:

TIPCLI_DISABLED=1 your-command

Local Testing

Use a custom API endpoint:

TIPCLI_API_URL=http://localhost:3000 your-command

Local API overrides are for rendering and integration checks. They must not be used as launch evidence or payout evidence.

Publishing

Before publishing the package, build and audit it:

pnpm --filter @tipcli/sdk build
pnpm --filter @tipcli/sdk publish:check
pnpm --filter @tipcli/sdk consumer:smoke
(cd packages/sdk && npm pack --dry-run)