@goatech/cli

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

Installation

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

Getting started

1. Create a developer API key

In your GoaTech 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 GOATECH_API_KEY=lp_dev_...
npx goatech init

That creates a goatech.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 goatech 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

goatech.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: .goatechrc, .goatechrc.json.

Environment variables

| Variable | Purpose | | ----------------- | --------------------------------------------------------------------------------------------------------- | | GOATECH_API_KEY | Bypass saved profiles for one-shot use. lp_dev_* for codegen; lp_sec_* for management. In CI, secret. | | GOATECH_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:
    GOATECH_API_KEY: ${{ secrets.GOATECH_API_KEY }}
  run: |
    pnpm goatech codegen
    git diff --exit-code src/generated/flags.ts

Commands

Codegen (needs goatech.config.json)

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

Live management (needs goatech login)

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

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

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

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

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

Examples

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

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

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

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

Troubleshooting

GOATECH_API_KEY environment variable is required. Create a dev key at your dashboard and export it: export GOATECH_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 goatech.config.json matches the slug shown in your dashboard.

License

MIT