Piglet - PostHog Management CLI

Use the piglet command-line interface to manage PostHog resources. This skill handles feature flags, cohorts, dashboards, insights, and projects across US Cloud, EU Cloud, or self-hosted PostHog instances.

When to activate

• User asks about feature flags: "what flags do we have", "is X flag enabled", "create a flag for Y"
• User wants to manage rollouts: "roll out feature X to 50%", "disable the beta flag"
• User needs cohort information: "list our cohorts", "create a cohort for power users"
• User asks about dashboards or insights: "what dashboards exist", "show me insight X"
• User wants to export PostHog configuration: "export all flags as JSON"

Prerequisites

1. Install piglet:

``bash uv tool install cased-piglet piglet --version ``

1. Configure authentication (one of):

```bash # Environment variables (recommended) export POSTHOGAPIKEY="phxyourkey" export POSTHOGPROJECTID="12345"

# Or config file: ~/.piglet/config.toml # apikey = "phxyourkey" # projectid = 12345 # host = "us" ```

1. Verify setup:

``bash piglet projects list ``

Core workflow

1. Confirm context

- Check which PostHog project the user wants to work with - Verify credentials are configured: piglet projects list - Note the host if not US Cloud (eu, or custom URL)

1. Feature flags

```bash # List all flags piglet flags list piglet flags list --active # only active piglet flags list --json # for parsing

# Get specific flag (by ID or key) piglet flags get my-feature-flag

# Create a flag piglet flags create --key new-flag --name "New Feature" --rollout-percentage 50

# Update rollout or status piglet flags update 123 --rollout-percentage 100 piglet flags update 123 --active piglet flags update 123 --inactive

# Delete (with confirmation) piglet flags delete 123 piglet flags delete 123 --yes # skip confirmation ```

1. Cohorts

``bash piglet cohorts list piglet cohorts list --static # only static cohorts piglet cohorts get 456 piglet cohorts create --name "Power Users" piglet cohorts create --name "Beta Testers" --static piglet cohorts update 456 --name "New Name" piglet cohorts delete 456 ``

1. Dashboards

``bash piglet dashboards list piglet dashboards list --pinned piglet dashboards get 789 piglet dashboards create --name "Engineering Metrics" piglet dashboards update 789 --pinned piglet dashboards delete 789 ``

1. Insights

``bash piglet insights list piglet insights list --saved piglet insights get abc123 # by short_id piglet insights create --name "Daily Active Users" piglet insights update 101 --name "Weekly Active Users" piglet insights delete 101 ``

1. Projects

``bash piglet projects list # list all accessible projects piglet projects get 12345 # get project details ``

Output formats

Piglet supports three output formats:

# Rich table (default) - human readable
piglet flags list

# JSON - for programmatic use
piglet flags list --json

# Plain tab-separated - for scripting
piglet flags list --plain
piglet flags list --plain | cut -f2    # extract just flag keys

Working with different hosts

# US Cloud (default)
piglet flags list

# EU Cloud
piglet --host eu flags list

# Self-hosted
piglet --host https://posthog.mycompany.com flags list

Examples

Check if a flag exists and its status

piglet flags get my-feature-flag

Create a gradual rollout

# Start at 10%
piglet flags create --key gradual-release --name "Gradual Release" --rollout-percentage 10

# Later, increase to 50%
piglet flags update <flag_id> --rollout-percentage 50

# Full rollout
piglet flags update <flag_id> --rollout-percentage 100

Export configuration for backup

piglet flags list --json > flags-backup.json
piglet cohorts list --json > cohorts-backup.json

Quick flag toggle

# Disable a flag immediately
piglet flags update 123 --inactive

# Re-enable
piglet flags update 123 --active

Find flags by grepping plain output

# Find all flags with "beta" in the key
piglet flags list --plain | grep beta

Common pitfalls & recoveries

• "API key required" - Set POSTHOGAPIKEY env var or use --api-key
• "Project ID required" - Set POSTHOGPROJECTID env var or use --project-id
• 403 Permission denied - API key lacks required scopes; generate a new key with appropriate permissions
• Wrong project - Verify project ID with piglet projects list, then use --project-id
• EU data - Remember to use --host eu for EU Cloud data

Best practices

• Use environment variables for credentials rather than CLI flags
• Use --json output when parsing results programmatically
• Use --plain output when piping to other CLI tools
• Always verify the target project before making changes
• Use --yes flag in scripts to skip confirmation prompts

References

• Command reference: [reference.md](reference.md)
• Piglet repository: https://github.com/cased/piglet