Managing Endpoints with the CLI

Experimental

The Endpoints CLI is experimental. Commands are prefixed with exp and may change in future releases.

The PostHog CLI provides commands to manage your Endpoints as code. You can version control your endpoint definitions, push changes from local YAML files, and pull existing endpoints for local editing.

Installation

Terminal
# Install the PostHog CLI
npm install -g @posthog/cli

# Authenticate
posthog-cli login

API key scope required

To manage Endpoints with the CLI, your personal API key needs the endpoint:write scope. If your endpoints use variables, you also need the insight_variable:read or insight_variable:write scope, depending on whether you intend to update endpoints using the CLI. You can create or update your API key in Personal API Keys.

Commands

List endpoints

List all endpoints in your project:

Terminal

posthog-cli exp endpoints list

Get endpoint details

View details of a specific endpoint:

Terminal
posthog-cli exp endpoints get <endpoint-name>

Run an endpoint

Execute an endpoint and see the results:

Terminal
# Run a remote endpoint
posthog-cli exp endpoints run <endpoint-name>

# Run from a local YAML file (without creating the endpoint)
posthog-cli exp endpoints run -f my-endpoint.yaml

# Pass variables
posthog-cli exp endpoints run <endpoint-name> --var customer_id=cust_123

# Output as JSON
posthog-cli exp endpoints run <endpoint-name> --json

Open in browser

Open an endpoint in the PostHog UI:

Terminal
posthog-cli exp endpoints open <endpoint-name>

Endpoints as code

Pull endpoints

Download endpoints from PostHog to local YAML files:

Terminal
# Pull a specific endpoint
posthog-cli exp endpoints pull my-endpoint

# Pull all endpoints
posthog-cli exp endpoints pull --all

# Pull to a specific directory
posthog-cli exp endpoints pull --all -o ./endpoints/

Push endpoints

Push local YAML files to PostHog:

Terminal
# Push a single file
posthog-cli exp endpoints push my-endpoint.yaml

# Push all YAML files in a directory
posthog-cli exp endpoints push ./endpoints/

# Preview changes without applying
posthog-cli exp endpoints push ./endpoints/ --dry-run

Diff endpoints

Compare local files with remote endpoints:

Terminal
posthog-cli exp endpoints diff ./endpoints/

YAML format

Endpoints are defined in YAML files:

YAML
name: daily_active_users
description: Count of unique users per day

# Simple HogQL query
query: |
  SELECT
    toDate(timestamp) as date,
    count(DISTINCT distinct_id) as users
  FROM events
  WHERE event = '$pageview'
  GROUP BY date
  ORDER BY date DESC

With variables

YAML
name: events_by_customer
description: Events for a specific customer
query: |
  SELECT event, count() as count
  FROM events
  WHERE properties.customer_id = {variables.customer_id}
  GROUP BY event

variables:
  - name: customer_id
    type: string
    default: "default_customer"

With materialization

YAML
name: hourly_metrics
description: Pre-computed hourly metrics
query: |
  SELECT count() FROM events

materialization:
  enabled: true
  schedule: "1hour"  # Options: 5min, 15min, 30min, 1hour, 2hour, 4hour, 6hour, 12hour, 24hour, 7day, 30day

Complex queries (insights)

For insight-based endpoints, use query_definition instead of query:

YAML
name: signup_funnel
description: User signup funnel

query_definition:
  kind: FunnelsQuery
  funnelsFilter:
    funnelVizType: steps
  series:
    - kind: EventsNode
      event: "$pageview"
      name: "Page View"
    - kind: EventsNode
      event: "signed_up"
      name: "Signed Up"

Workflow example

Terminal
# 1. Pull existing endpoints
posthog-cli exp endpoints pull --all -o ./posthog/endpoints/

# 2. Edit locally, commit to git
git add posthog/endpoints/
git commit -m "feat: add new customer metrics endpoint"

# 3. Preview changes
posthog-cli exp endpoints diff ./posthog/endpoints/

# 4. Push to PostHog
posthog-cli exp endpoints push ./posthog/endpoints/