gkit

Private, profile-bound CLI for agent-first access to growth providers. This repository has one CLI and one workspace package: gkit.

The reviewed provider surface includes DataForSEO, PostHog, Google Ads, Google Search Console, and Bing Webmaster.

Install

gkit is private and is not published to npm. Install it once per machine from the repository checkout:

bun install
bun link --cwd packages/gkit

gkit --schema

Discover capabilities

Discovery commands are offline and do not load a profile or resolve secrets:

gkit --schema
gkit docs --provider gsc
gkit describe --id gsc.search-analytics.query

Configure an App profile

Provider execution must bind exactly one App profile. Create one JSON file at $XDG_CONFIG_HOME/gkit/profiles/<app>.json, or at ~/.config/gkit/profiles/<app>.json when XDG_CONFIG_HOME is unset:

{
  "version": 1,
  "name": "my-app",
  "providers": {
    "posthog": {
      "config": {
        "host": "https://us.posthog.com",
        "projectId": "12345"
      },
      "secrets": {
        "apiToken": "env:MY_APP_POSTHOG_TOKEN"
      }
    },
    "gsc": {
      "config": {
        "siteUrl": "sc-domain:example.com"
      },
      "secrets": {
        "serviceAccountFile": "env:MY_APP_GSC_SERVICE_ACCOUNT_FILE"
      }
    }
  }
}

Profiles contain non-secret provider defaults and env: references only. Keep the referenced values in the team's secret manager and inject them into the gkit process at runtime. Do not put plaintext credentials in the profile, repository, Agent instructions, command arguments, or shell startup files.

For local use, gkit also loads an optional profile-adjacent environment file at ~/.config/gkit/profiles/<app>/.env after the profile is selected. Keep this file outside the repository with mode 0600; explicitly supplied process environment values take precedence over values in the file.

Select a profile explicitly:

gkit --profile my-app posthog doctor
gkit --profile my-app gsc doctor

Or bind it for one process through the environment:

GKIT_PROFILE=my-app gkit posthog doctor

--profile takes precedence over GKIT_PROFILE. One invocation never merges or falls back to another App profile. Compare multiple Apps by running separate invocations and joining their outputs outside gkit.

Configure an Agent

Agents do not need provider-specific CLIs or their own copies of credentials. A repository can add the following contract to its AGENTS.md:

## Growth provider access

- Use `gkit` for all growth-provider access.
- The default App profile for this repository is `<app-name>`.
- Before a live request, run `gkit --profile <app-name> <provider> doctor`.
- Discover capabilities with `gkit --schema`,
  `gkit docs --provider <provider>`, and
  `gkit describe --id <capability-id>`.
- Never read, record, or print provider secrets.

The Agent only needs to know that it should use gkit and which App profile owns the task. CLI installation and secret access belong to the machine or runtime.

All former standalone provider and local-tool packages were removed after the sole CLI consumer explicitly selected a hard cutover. There are no compatibility aliases or deprecated binaries. Historical behavior evidence remains under packages/gkit/evals.

Verification

bun run eval
bun run check-types
bun run test
bun run verify:package