:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
chore(hog): draft the posthog-cli to hog migration guide (#125564)
Rafael Audibert7c020542473b
diff --git a/hog/MIGRATING.md b/hog/MIGRATING.mdnew file mode 100644index 000000000000..048e44ecddb7--- /dev/null+++ b/hog/MIGRATING.md@@ -0,0 +1,114 @@+# Moving from posthog-cli to hog++> [!NOTE]+> This guide is a draft. hog isn't published yet, and the guide will move to posthog.com when it is.++hog is version 1 of the PostHog command line. It does what posthog-cli does, with new command names, `HOG_` environment variables, and output that agents can read.+Most moves take three steps: install hog, rename the environment variables, and rewrite each command with the tables below.++## What stays the same++- **Your login.** Both CLIs read and write `~/.posthog/credentials.json`, so `posthog-cli login` works for hog, and `hog auth login` works for posthog-cli.+- **Uploads.** hog sends the same bytes and content hashes, so either CLI can re-upload what the other uploaded. Chunk IDs and releases don't change.+- **posthog.json.** hog reads the `languages` entries `posthog-cli exp schema` writes, and the endpoint YAML files `posthog-cli exp endpoints` writes.+- **Global flags.** `--host`, `--dotenv-file`, `--no-fail`, `--skip-ssl-verification` and `--rate-limit` work as before, before or after the command.++## Environment variables++hog reads only `HOG_` variables. Rename these:++| posthog-cli | hog |+| ---------------------------------------------- | ------------------------ |+| `POSTHOG_CLI_API_KEY`, `POSTHOG_CLI_TOKEN` | `HOG_API_KEY` |+| `POSTHOG_CLI_PROJECT_ID`, `POSTHOG_CLI_ENV_ID` | `HOG_PROJECT_ID` |+| `POSTHOG_CLI_HOST` | `HOG_HOST` |+| `POSTHOG_CLI_DOTENV_FILE` | `HOG_DOTENV_FILE` |+| `POSTHOG_CLI_DRY_RUN` | `HOG_DRY_RUN` |+| `POSTHOG_CLIENT_RATE_LIMIT` | `HOG_RATE_LIMIT` |+| `POSTHOG_CLI_SOURCEMAP_UPLOAD_CONCURRENCY` | `HOG_UPLOAD_CONCURRENCY` |+| `POSTHOG_RELEASE_MODE` | `HOG_RELEASE_MODE` |+| `POSTHOG_HOME` | `HOG_HOME` |++A dotenv file that `--dotenv-file` names needs the new names too.+In CI, you can set both sets of names while some jobs still run posthog-cli.++## Commands++| posthog-cli | hog |+| -------------------------------------------------- | ---------------------------------------------------------------------------- |+| `login` | `auth login`, plus `auth status` and `auth logout` |+| `sourcemap inject --directory <dir>` | `error-tracking inject <dir>` |+| `sourcemap upload --directory <dir>` | `error-tracking upload <dir>` |+| `sourcemap process --directory <dir>` | `error-tracking process <dir>` |+| `hermes inject --directory <dir>` | `error-tracking inject <dir>` |+| `hermes clone -m <file1> -c <file2>` | `error-tracking clone <file1> <file2>` |+| `hermes upload --directory <dir>` | `error-tracking upload <dir>` |+| `dsym upload --directory <dir>` | `error-tracking upload <dir>` |+| `proguard upload --path <file> --map-id <id>` | `error-tracking upload <file> --map-id <id>` |+| `symbol-sets upload --directory <dir>` | `error-tracking upload <dir>` |+| `symbol-sets download --id <id> -o <dir>` | `error-tracking download <id> --output-dir <dir>` |+| `symbol-sets download --ref <ref>` | `error-tracking download <ref>`, with `--ref` when the ref looks like an ID |+| `symbol-sets extract <file> -o <dir>` | `error-tracking extract <file> --output-dir <dir>` |+| `release resolve` | `error-tracking release -o text` |+| `release resolve --json` | `error-tracking release -o json` |+| `exp query run <query>` | `query run <query>` |+| `exp query check <query>` | `query check <query>` |+| `exp endpoints list`, `get`, `open`, `run`, `diff` | `endpoints list`, `get`, `open`, `run`, `diff` |+| `exp endpoints pull -o <dir>` | `endpoints pull --to <dir>` |+| `exp endpoints push` | `endpoints push` |+| `exp schema pull -o <file>` | `schema pull --file <file>` |+| `exp schema status` | `schema status` |+| `api tools`, `search`, `info`, `schema`, `call` | `api tools`, `search`, `info`, `schema`, `call`, with `-o json` for `--json` |++`hog et` is short for `hog error-tracking`.+`hog error-tracking upload` detects what each path holds, so one command uploads JavaScript, Hermes, ProGuard, dSYM and ELF symbols, and `--kind` skips detection.+Run `hog <command> --help` for every flag, or `hog commands -o json` for all of them at once.++Not in hog yet, so keep posthog-cli for them:++- `update`. It becomes `hog upgrade` when hog ships.+- `api skill` and `api agents-md`. They come back as top-level commands.+- `exp logs import`, `exp task`, and `exp query editor`.++hog lists these and prints the posthog-cli command to run instead.++## Flags that changed++- **Paths are arguments.** `--directory`, `--path`, `-m` and `-c` become positional arguments, and one command takes several paths.+- **`-o` is the output format.** It takes `text` or `json`. posthog-cli's `-o` paths become `--to` in `endpoints pull`, `--file` in `schema pull`, and `--output-dir` in `download` and `extract`.+- **`--include`, `--exclude` and `--stdin` are gone.** List the paths as arguments, or keep them in `errorTracking.sources` in `posthog.json`, where `ignore` globs skip files.+- **`--skip-release-on-fail` is gone.** hog always retries without the release when PostHog says a chunk belongs to another release, as posthog-cli did.+- **`--main-dsym` is gone.** hog takes the release from `--release-name`, `--release-version`, `--info-plist`, `posthog.json` or git.+- **`--debug` is global.** It prints each request to stderr for every command.++## Dry runs++posthog-cli's `--dry-run` skipped uploads and `release` without doing anything.+hog's `--dry-run` does the work and shows the result without changing anything: uploads list each symbol set with its content hash, and `schema pull`, `endpoints pull` and `push` show what they would change.++`HOG_DRY_RUN=1` turns on `--dry-run` for every command that has one. Commands that only read run as usual.+`auth login` and `auth logout` have no dry run, so they fail when `HOG_DRY_RUN` is set.++## Output++hog prints tables and colors for a person at a terminal, and JSON when an agent runs it, when stdout is a pipe, or with `-o json`.+A script that reads hog's output should pass `-o text` or `-o json`, so the format doesn't depend on where it runs:++```bash+# before+RELEASE_ID=$(posthog-cli release resolve)+# after+RELEASE_ID=$(hog error-tracking release -o text)+```++Errors go to stderr, as JSON with a stable `code` in JSON mode.+Exit codes are 0 on success, 1 when a command fails or reports a problem, and 2 for usage errors.+`--no-fail` turns 1 into 0, and leaves 2 alone.++## posthog.json++hog reads more from `posthog.json` than posthog-cli did: the host, error tracking sources and release, the endpoints folder, and defaults for `--no-fail` and `--rate-limit`.+When the file is invalid, every command stops except `hog config check`, which lists the problems.++posthog-cli rewrites `posthog.json` with only `languages` when it pulls a schema, so it drops hog's settings.+Run only hog's `schema pull` once a project uses hog settings.diff --git a/hog/README.md b/hog/README.mdindex b75b91ffe438..8573ea8a6bea 100644--- a/hog/README.md+++ b/hog/README.md@@ -40,16 +40,23 @@ The commands `posthog-cli` keeps under `exp` (`query`, `endpoints`, `logs`, `tas## What's left-hog replaces posthog-cli once everything below is done.+hog replaces posthog-cli in three steps: settle the CLI, ship it, then move everyone over.+[MIGRATING.md](MIGRATING.md) drafts the guidance for people moving from `posthog-cli` to `hog`, and it moves to posthog.com when hog ships.-First, the commands that make hog a complete CLI:+First, settle the CLI:-- [ ] `hog api skill` and `hog api agents-md`, which install PostHog agent skills and the AGENTS.md snippet.+- [ ] `hog upgrade`, which updates hog to the latest version. It downloads the release binaries, so it lands with distribution. Until then it points to `posthog-cli update`.+- Agent skills and the AGENTS.md snippet come back as top-level commands, designed fresh rather than ported from `posthog-cli api skill` and `api agents-md`. Until then, hog points to those.-Then, once the commands above work:+Then ship it:-- [ ] Callers: the SDKs, build plugins and scripts that run `posthog-cli` with its arguments. Move them to hog, or give hog a `posthog-cli` entry point that translates the arguments.-- [ ] Distribution: a binary for each platform, macOS signing and notarization, the npm package, the Homebrew formula, `hog update`, CI on Linux and Windows.+- [ ] Distribution: a binary for each platform, macOS signing and notarization, the npm package, the Homebrew formula, and CI on Linux and Windows.++Then move everyone over:++- [ ] Publish the migration guide on posthog.com.+- [ ] Callers: move the SDK build integrations (posthog-js, React Native and Expo, the Android Gradle plugin, the iOS build script), the error tracking onboarding in the web app, and the posthog.com docs from `posthog-cli` to `hog`.+- [ ] A `posthog-cli` entry point in hog that translates posthog-cli's commands, flags and `POSTHOG_CLI_` variables, so the posthog-cli package can ship hog and old pipelines and SDK versions keep working.Not planned:diff --git a/hog/src/cli.test.ts b/hog/src/cli.test.tsindex d9db0b1c97ae..608f31277b3d 100644--- a/hog/src/cli.test.ts+++ b/hog/src/cli.test.ts@@ -68,6 +68,7 @@ describe('hog', () => {test.each([['login', 'Did you mean `hog auth login`?'],['sourcemap', '`sourcemap` is `hog error-tracking inject|upload|process` in hog.'],+ ['exp', '`exp` is `hog query|endpoints|schema` in hog.'],])('a command that moved, like %s, points to its new name', async (name, message) => {const result = await runHog([name, 'upload'])expect(result.exitCode).toBe(2)diff --git a/hog/src/cli.ts b/hog/src/cli.tsindex b37d0314d236..fb55fc7d8369 100644--- a/hog/src/cli.ts+++ b/hog/src/cli.ts@@ -365,6 +365,11 @@ const RENAMED: Record<string, { to: string; hint: string }> = {to: 'error-tracking upload',hint: 'Pass the mapping as an argument instead of --path, as in `hog error-tracking upload mapping.txt --map-id <id>`.',},+ exp: {+ to: 'query|endpoints|schema',+ hint: 'The experimental commands are top level in hog, as in `hog endpoints pull` for `posthog-cli exp endpoints pull`.',+ },+ update: { to: 'upgrade', hint: 'Run `hog upgrade`.' },}function toHogError(caught: unknown): HogError {diff --git a/hog/src/commands/legacy.ts b/hog/src/commands/legacy.tsindex 8393383729b6..f37157613972 100644--- a/hog/src/commands/legacy.ts+++ b/hog/src/commands/legacy.ts@@ -6,5 +6,5 @@ export const LEGACY_COMMANDS: CommandTree = {use: 'posthog-cli exp logs',}),tasks: defineLegacy({ description: 'List, track and update PostHog tasks', use: 'posthog-cli exp task' }),- update: defineLegacy({ description: 'Update hog to the latest version', use: 'posthog-cli update' }),+ upgrade: defineLegacy({ description: 'Upgrade hog to the latest version', use: 'posthog-cli update' }),}