Skip to content

: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.

chore(hog): draft the posthog-cli to hog migration guide (#125564)

Rafael Audibert7c020542473b
diff --git a/hog/MIGRATING.md b/hog/MIGRATING.md
new file mode 100644
index 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.md
index 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.ts
index 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.ts
index 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.ts
index 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' }),
}