Insightful Pipe

Query and manage marketing data across 40+ platforms — Google Analytics, Google Ads, Facebook Ads, Instagram, Shopify, HubSpot, Klaviyo, TikTok, LinkedIn, an...

Security Scan

The skill's requirements, instructions, and install method match its stated purpose of running an external CLI to query/manage marketing data; nothing obvious is requesting unrelated credentials or system access.

Purpose & Capability

Name/description (marketing data across many platforms) aligns with requiring an external 'insightfulpipe' CLI and a single service token (INSIGHTFULPIPE_TOKEN). The declared binary and env var are appropriate for a CLI-based aggregator.

Instruction Scope

SKILL.md contains concrete CLI commands (accounts, helper, query, action) limited to the InsightfulPipe tool and standard piping to tools like jq. Write operations are explicitly gated by user confirmation (--yes). The instructions do not attempt to read unrelated system files or unstated environment variables.

Install Mechanism

Install is an npm package (npm install -g insightfulpipe). This is a reasonable mechanism for a CLI JS package, but npm packages carry supply-chain risk—verify the package publisher and contents before installing globally.

Credentials

Only INSIGHTFULPIPE_TOKEN is required. That is proportional: a single token is expected to authorize access to the connected marketing platforms. No unrelated credentials or config paths are requested.

Persistence & Privilege

Skill is not always-enabled and does not request system-wide configuration or modify other skills. It relies on an external binary and a token, which is typical and limited in scope.

Scan Findings in Context

[regex-scan-none] expected: No regex-based findings were reported. This is expected because the skill is instruction-only (SKILL.md) and contains no embedded code files for the scanner to analyze.

Assessment

This skill delegates work to an external CLI (npm package 'insightfulpipe') and needs an INSIGHTFULPIPE_TOKEN to access your marketing data. Before installing: 1) verify the npm package publisher and check the package source/code and permissions (to reduce supply-chain risk); 2) use a token with least privilege and consider creating a scoped service token for this tool; 3) install and test the CLI in a non-critical environment first (or inside a container) to review what network endpoints it calls; 4) for write actions, confirm the prompts or avoid using --yes unless you trust the command. These steps will reduce risk even though the skill itself appears coherent with its stated purpose.

Install InsightfulPipe if it doesn't exist

npm install -g insightfulpipe

npm release: https://www.npmjs.com/package/insightfulpipe

---

Property	Value
name	insightfulpipe
description	Query marketing data across analytics, ads, social, ecommerce, and SEO platforms
allowed-tools	Bash(insightfulpipe:*)

---

Authentication

The INSIGHTFULPIPE_TOKEN environment variable is expected to be pre-configured. If a command fails with "Invalid token" or "Not authenticated", inform the user that their token needs to be configured.

---

Core Workflow

Every query follows: discover → schema → execute. Read operations (query) can run directly. Write operations (action) should be confirmed with the user before executing.

# 1. Get account IDs (workspace_id, brand_id, source IDs)
insightfulpipe accounts --platform <platform> --json

# 2. See available actions
insightfulpipe helper <platform>

# 3. Get request body schema for specific actions
insightfulpipe helper <platform> --actions <action1>,<action2>

# 4. Execute read query
insightfulpipe query <platform> -b '{"action":"<action>","workspace_id":<id>,"brand_id":<id>,...}'

# 5. Execute write operation (requires --yes)
insightfulpipe action <platform> -b '{"action":"<action>",...}' --yes

---

Platform Examples

Google Analytics — Top Pages

insightfulpipe accounts --platform google-analytics --json
insightfulpipe helper google-analytics --actions pages
insightfulpipe query google-analytics -b '{
  "action": "pages",
  "workspace_id": xxx,
  "brand_id": xxx,
  "property_id": "properties/xxx",
  "dimensions": ["pagePath"],
  "metrics": ["screenPageViews", "activeUsers"],
  "start_date": "2026-03-01",
  "end_date": "2026-03-20",
  "limit": 10
}'

Google Analytics — Traffic Sources

insightfulpipe query google-analytics -b '{
  "action": "traffic_sources",
  "workspace_id": xxx,
  "brand_id": xxx,
  "property_id": "properties/xxx",
  "dimensions": ["sessionSource", "sessionMedium"],
  "metrics": ["sessions", "totalUsers", "bounceRate"],
  "start_date": "2026-03-01",
  "end_date": "2026-03-20"
}'

Google Analytics — Freeform Report

insightfulpipe query google-analytics -b '{
  "action": "get_report",
  "workspace_id": xxx,
  "brand_id": xxx,
  "property_id": "properties/xxx",
  "dimensions": ["date", "country"],
  "metrics": ["activeUsers", "sessions"],
  "start_date": "2026-03-01",
  "end_date": "2026-03-20"
}'

Google Search Console — Top Queries

insightfulpipe query google-search-console -b '{
  "action": "search_analytics",
  "workspace_id": xxx,
  "brand_id": xxx,
  "site_url": "https://example.com/",
  "dimensions": ["query"],
  "start_date": "2026-03-01",
  "end_date": "2026-03-20",
  "row_limit": 10
}'

Google Search Console — Pages by Country

insightfulpipe query google-search-console -b '{
  "action": "search_analytics",
  "workspace_id": xxx,
  "brand_id": xxx,
  "site_url": "https://example.com/",
  "dimensions": ["page", "country"],
  "start_date": "2026-03-01",
  "end_date": "2026-03-20",
  "row_limit": 20
}'

Google Sheets — Peek at Columns Then Query

# First peek to see column names
insightfulpipe query google-sheets -b '{
  "action": "get_sheet_peak",
  "workspace_id": xxx,
  "brand_id": xxx,
  "spreadsheet_id": "xxx",
  "sheet_id": "0"
}'

# Then query with filters using exact column names from peek
insightfulpipe query google-sheets -b '{
  "action": "query_sheet_data",
  "workspace_id": xxx,
  "brand_id": xxx,
  "spreadsheet_id": "xxx",
  "sheet_id": "0",
  "select": "Name,Email,Status",
  "where": "Status=Active",
  "limit": 50
}'

Google Sheets — Write Cells

insightfulpipe action google-sheets -b '{
  "action": "update_cells",
  "workspace_id": xxx,
  "brand_id": xxx,
  "spreadsheet_id": "xxx",
  "sheet_id": "0",
  "range": "A1:C2",
  "values": [["Name", "Email", "Status"], ["John", "[e-mail]", "Active"]]
}' --yes

Shopify — Recent Orders

insightfulpipe query shopify -b '{
  "action": "get_orders",
  "workspace_id": xxx,
  "brand_id": xxx,
  "status": "any",
  "limit": 10
}'

Shopify — Products

insightfulpipe query shopify -b '{
  "action": "get_products",
  "workspace_id": xxx,
  "brand_id": xxx,
  "limit": 10
}'

Any Other Platform

# Same pattern works for all platforms:
insightfulpipe helper <platform>                        # See actions
insightfulpipe helper <platform> --actions <action>     # Get body schema
insightfulpipe query <platform> -b '{...}'              # Execute

Supported platforms include: facebook-ads, instagram, tiktok-ads, tiktok-pages, linkedin-ads, linkedin-pages, hubspot, klaviyo, mailchimp, stripe, slack, telegram, and many more. Run insightfulpipe platforms to see the full list.

---

Common Patterns

Pattern 1: Pipe to jq

# Extract just page paths from GA response
insightfulpipe query google-analytics -b '{...}' | jq '.data[].pagePath'

# Get total sessions
insightfulpipe query google-analytics -b '{...}' | jq '[.data[].sessions] | add'

Pattern 2: Compare Data Across Platforms

# GA traffic
GA=$(insightfulpipe query google-analytics -b '{
  "action": "traffic_sources", "workspace_id": xxx, "brand_id": xxx,
  "property_id": "properties/xxx",
  "dimensions": ["sessionSource"], "metrics": ["sessions"],
  "start_date": "2026-03-01", "end_date": "2026-03-20"
}')

# GSC queries
GSC=$(insightfulpipe query google-search-console -b '{
  "action": "search_analytics", "workspace_id": xxx, "brand_id": xxx,
  "site_url": "https://example.com/",
  "dimensions": ["query"],
  "start_date": "2026-03-01", "end_date": "2026-03-20", "row_limit": 10
}')

echo "$GA" | jq '.data[:5]'
echo "$GSC" | jq '.data[:5]'

Pattern 3: Write Operations

# Always use "action" (not "query") and --yes for writes
insightfulpipe action google-sheets -b '{
  "action": "create_sheet",
  "workspace_id": xxx,
  "brand_id": xxx,
  "spreadsheet_id": "xxx",
  "title": "New Sheet"
}' --yes

Pattern 4: Use Prompts for Guided Analysis

insightfulpipe prompts google-analytics            # List templates
insightfulpipe prompts google-analytics --id 12    # Get specific prompt

---

Gotchas

1. Never guess the request body — always run helper <platform> --actions <action> first.
2. Replace ALL "xxx" placeholders — get real values from accounts --platform <platform> --json.
3. GA property_id needs "properties/" prefix — use "properties/510157516" not "510157516".
4. Date format is YYYY-MM-DD — use "2026-03-20" not "2026-03-20T00:00:00Z".
5. Use query for reads, action --yes for writes — using the wrong one will fail.
6. Google Sheets: peek before query — call get_sheet_peak first to see column names.
7. Different platforms have different source IDs — GA uses property_id, GSC uses site_url, Shopify uses shop_domain, Facebook Ads uses ad_account_id.
8. Empty data is not an error — {"status":"success","data":[]} means no data matched your filters.
9. Token should be pre-configured — if auth fails, inform the user to check their token configuration.
10. Confirm write operations with the user — always ask before running insightfulpipe action. Read operations via insightfulpipe query are safe to run directly.

---

All Commands

# Discovery
insightfulpipe platforms                              # All supported platforms
insightfulpipe accounts --platform <platform> --json  # Account IDs
insightfulpipe sources --platform <platform>          # Sources with IDs
insightfulpipe brands --workspace <id>                # Brand metadata
insightfulpipe whoami                                 # Current user
insightfulpipe doctor                                 # Check auth

# Schema
insightfulpipe helper <platform>                      # List actions
insightfulpipe helper <platform> --actions <a1>,<a2>  # Body schema

# Execute
insightfulpipe query <platform> -b '<json>'           # Read data
insightfulpipe query <platform> -f file.json          # Read from file
insightfulpipe action <platform> -b '<json>' --yes    # Write data

# Prompts
insightfulpipe prompts <platform>                     # List templates
insightfulpipe prompts <platform> --id <id>           # Get prompt