@sheepit-ai/cli

Command-line tooling for Sheepit. Generate type-safe Flag constants, manage releases, run platform operations from your terminal or CI pipeline.

Installation

For project-scoped use (codegen in CI / npm scripts):

pnpm add -D @sheepit-ai/cli
# or
npm install --save-dev @sheepit-ai/cli
# or
yarn add --dev @sheepit-ai/cli

For global use on your laptop, install the unscoped sheepit shim (an exact-pin re-export of @sheepit-ai/cli):

npm install -g sheepit
# then
sheepit login

Getting started

1. Create a developer API key

In your Sheepit dashboard → Settings → API Keys → Create API Key → select type Developer (CLI / codegen). Copy the key (shown once) — it starts with lp_dev_.

Dev keys are meant for dev-time tools and CI pipelines. They can read project schemas (flag definitions, flag schemas, etc.) but cannot write destructive changes or send events. Never commit one to a public repo.

2. Initialize your project

export SHEEPIT_API_KEY=lp_dev_...
npx sheepit init

That creates a sheepit.config.json like:

{
  "projectSlug": "my-app",
  "codegen": {
    "platforms": ["web", "ios"],
    "outputs": {
      "typescript": "./src/generated/flags.ts",
      "swift": "./ios/Generated/Flags.swift"
    }
  }
}

Commit this file to git. It has no secrets.

3. Generate typed constants

Whenever you add or change a flag in the dashboard, run:

npx sheepit codegen

This fetches the current flag definitions and writes out typed constants.

4. Use the constants in your code

// Before — string literals; typos silently never match
const show = useFlag("show_dashbaord_link", false);

// After — typed constants; typos are compile errors
import { Flags } from "./generated/flags";
const show = useFlag(Flags.show_dashboard_link, false);

Configuration

sheepit.config.json

{
  "projectSlug": "my-app", // required — matches the slug in your dashboard
  "apiUrl": "https://...", // optional — defaults to https://api.goatech.ai
  "codegen": {
    "platforms": ["web", "ios", "android", "server"],
    "outputs": {
      "typescript": "./src/generated/flags.ts",
      "swift": "./ios/Generated/Flags.swift",
      "kotlin": "./android/generated/Flags.kt",
    },
  },
}

Alternate filenames that are auto-discovered, in lookup order: sheepit.config.json (default), .sheepitrc, .sheepitrc.json, .goatechrc, .goatechrc.json (back-compat for pre-rebrand projects; not auto-rewritten).

Environment variables

| Variable | Purpose | | ----------------- | --------------------------------------------------------------------------------------------------------- | | SHEEPIT_API_KEY | Bypass saved profiles for one-shot use. lp_dev_* for codegen; lp_sec_* for management. In CI, secret. | | SHEEPIT_API_URL | Optional. Override API endpoint. Takes priority over the active profile's URL. |

CI usage

Run codegen in CI to verify the committed generated files match the live schema:

# .github/workflows/ci.yml
- name: Check Flag codegen is up to date
  env:
    SHEEPIT_API_KEY: ${{ secrets.SHEEPIT_API_KEY }}
  run: |
    pnpm sheepit codegen
    git diff --exit-code src/generated/flags.ts

Commands

Codegen (needs sheepit.config.json)

| Command | Description | | ----------------- | ------------------------------------------------------- | | sheepit init | Create sheepit.config.json with an interactive prompt | | sheepit codegen | Regenerate typed constants from the dashboard | | sheepit help | Show help |

Live management (needs sheepit login)

Authenticate once with a secret key (lp_sec_...) to unlock read/write access:

sheepit login              # prompts for profile name, API URL, key
sheepit whoami             # show active profile
sheepit use staging        # switch profile

Stored at ~/.sheepit/credentials.json (chmod 0600). Multiple profiles supported — pass --profile <name> per-command, or switch with sheepit use.

| Command | Description | | --------------------------------------------------------- | ------------------------------------------------------------- | | sheepit flags list [--status active \| --platform ios] | List flags with status, type, default, platforms | | sheepit flags get <key-or-id> | Show one flag | | sheepit flags kill <key> [--reason ...] | Activate kill switch (prompts unless --yes, admin role) | | sheepit flags restore <key> | Clear an active kill switch (admin role) | | sheepit rollouts list [--flag key] [--status active] | List rollouts; resolves --flag key to id | | sheepit rollouts {start\|pause\|advance\|complete} <id> | Drive a rollout | | sheepit releases list [--platform ios --channel stable] | Release health snapshot | | sheepit releases {get\|health} <id> | Health breakdown + rollout decisions | | sheepit events names [--search ...] | Event catalog (names + counts + last seen) | | sheepit events query --event foo --since 24h | Time-series; --since 30m\|24h\|7d or explicit --from/--to | | sheepit crashes list [--status unresolved] | Crash groups (mobile SDK) | | sheepit crashes {get\|reports} <id> | Group details or paginated reports | | sheepit audit tail [--resource-type flag] | Recent audit entries | | sheepit integrations github {list\|link\|unlink} | Manage GitHub repo links (link prints a webhook secret once) |

Output format

Auto-detect: table when stdout is a TTY, JSON when piped. Force either:

sheepit flags list --json              # explicit JSON
sheepit crashes list | jq '.'          # JSON by default (piped)
sheepit flags list --output table      # force table even in a pipe

Examples

# Flip a kill switch in staging
sheepit --profile staging flags kill show_dashboard_link --reason "incident 2026-04-18"

# Page event volume hourly for last 24h
sheepit events query --event module_viewed --since 24h --interval 1h | jq

# Top high-priority unresolved crashes on iOS
sheepit crashes list --status unresolved --priority high --platform ios

# Check who changed what in the last hour
sheepit audit tail --since 1h --limit 100

Troubleshooting

SHEEPIT_API_KEY environment variable is required. Create a dev key at your dashboard and export it: export SHEEPIT_API_KEY=lp_dev_...

Fetch definitions for web failed: 403 Check that your API key starts with lp_dev_ or lp_sec_. Publishable keys (lp_pub_) cannot access codegen endpoints.

Fetch definitions for ios failed: 404 The API can't find your project. Verify projectSlug in sheepit.config.json matches the slug shown in your dashboard.

License

MIT