InsightfulPipe CLI

What the CLI can do

• Discover: platforms, workspaces, brands and accounts --platform <platform> return the workspace, brand and account identifiers an agent needs.
• Read schemas: helper <platform> lists the actions a platform exposes to you, and helper <platform> --actions <a,b> returns the exact request body for each.
• Run reads: query <platform> runs reports and listings with a JSON body from -b or a file from -f.
• Run writes: action <platform> runs creates, updates, pauses and other changes, after a confirmation prompt.
• Prompts: prompts <platform> lists prompt templates, and --id fetches one.
• Setup and checks: auth, whoami, doctor, config and, from version 0.2.0, use.

Before you start

• Node.js 18 or later.
• An InsightfulPipe workspace with at least one connected account. See First Connection.
• An API key. Keys start with ip_sk_ and belong to one workspace.
• Plans start at $29.99/month with a 7-day free trial. CLI access is included in every plan.

Install and authenticate

1. Install the package: npm install -g insightfulpipe
2. In the InsightfulPipe app, open Settings > API Keys and create a key.
3. Run insightfulpipe auth and paste the key when prompted.
4. Run insightfulpipe doctor to check the token, API URL and connectivity.
5. Run insightfulpipe whoami to confirm the user and workspace.

insightfulpipe auth stores the key in your operating system keyring. Add --insecure-storage to write it to ~/.insightfulpipe/config.json instead.

Use it from an agent, CI or a sandbox

• Set the INSIGHTFULPIPE_TOKEN environment variable instead of running auth. The CLI reads it before the keyring and the config file.
• Claude Code: Claude Code runs the CLI through its shell tool. The npm package ships a SKILL.md that documents the workflow; copy it into your Claude Code skills folder.
• Codex: add the workflow to your AGENTS.md so Codex reads the schema with helper before it queries. The CLI calls app.insightfulpipe.com, so the agent needs network access.
• OpenClaw: the same skill is published on ClawHub. When npm installs the package on a machine with an OpenClaw skills folder, it copies SKILL.md there.

Core workflow

Never guess a request body. Find the IDs, read the schema, then run the action:

insightfulpipe accounts --platform google-analytics
insightfulpipe helper google-analytics --actions get_report
insightfulpipe query google-analytics -b '{"action":"get_report","workspace_id":123,"brand_id":456,"property_id":"789","dimensions":["date"],"metrics":["sessions"],"start_date":"2026-08-01","end_date":"2026-08-07"}'

Replace the IDs with the values accounts returns, and copy the body shape from helper.

From version 0.2.0 you can save a default workspace and brand so you don't repeat them:

insightfulpipe use -w <workspace_id> -b <brand_id>
insightfulpipe use --clear

Run insightfulpipe use on its own to adopt your only workspace. Per-call --workspace and --brand options override the saved scope, and a body that already states the IDs is left unchanged.

Command reference

• insightfulpipe auth: save your API key (--insecure-storage writes it to the config file).
• insightfulpipe whoami: show the authenticated user.
• insightfulpipe doctor: check configuration and API connectivity.
• insightfulpipe platforms: list platform slugs.
• insightfulpipe workspaces: list the workspaces you can access.
• insightfulpipe brands: list brands and brand IDs.
• insightfulpipe accounts --platform <platform>: list connected accounts with their IDs.
• insightfulpipe helper <platform> --actions <a,b>: list actions, or get exact request bodies.
• insightfulpipe query <platform> -b '<json>': run a read; use -f body.json for a file.
• insightfulpipe action <platform> -f body.json: run a write; --yes skips the prompt.
• insightfulpipe prompts <platform>: list prompt templates; --id <id> fetches one, and --custom --workspace <id> --id <id> fetches a custom prompt.
• insightfulpipe config: show configuration; --set-url and --set-timeout change the API URL and request timeout.
• insightfulpipe raw: send a raw request to the universal dispatcher.

Run insightfulpipe <command> --help for every option. The older names query_contexts, sources, query_data and execute_action still work.

Platform slugs

Platform slugs match the MCP server pages, for example google-ads, google-analytics, facebook-ads, shopify and klaviyo. The exceptions are YouTube (youtube-analytics and youtube-data), Enrichment Crawlers (enrichment-crawlers), PageSpeed Insights (pagespeed-insights) and Screenshots (screenshot). If a platform is missing from platforms, helper <platform> still tells you whether it works.

Read vs write and safety

• Use query for reads and action for writes. In a terminal, action asks Execute write action "<action>" on "<platform>"? [y/N]. In non-interactive mode it fails unless you pass --yes.
• The CLI gets no extra permissions. Each connected account keeps its Read Only or Read & Write access, and owners, administrators and operators choose its enabled actions in Configure actions for this account. Disabled actions are hidden from helper and blocked if called.
• Destructive actions such as deletes stay off until someone enables them for the account.
• Write actions need the Owner, Administrator or Operator role. Members with the User role can only run the enabled read actions on accounts granted to them.
• An API key belongs to one workspace, so an agent using it can't reach accounts in another workspace.
• Before you give an agent --yes, turn off the write actions it shouldn't run on each account.

Output and configuration

• From version 0.2.0 every command prints JSON by default, and --table switches to readable columns. Version 0.1.x has a --json flag instead.
• Errors go to stderr with exit code 1, so piping results into jq stays clean.
• The default API URL is https://app.insightfulpipe.com. The CLI also reads INSIGHTFULPIPE_API_URL and INSIGHTFULPIPE_TIMEOUT_MS.

Limits

• The CLI reaches only accounts connected in the key's workspace, through the actions enabled on them.
• It doesn't connect platforms; you connect accounts in the InsightfulPipe app.
• Platform API limits apply, the same as over MCP.

Troubleshooting

• `doctor` reports an authentication problem: create a new key under Settings > API Keys and run insightfulpipe auth again. If INSIGHTFULPIPE_TOKEN is set, it takes priority over the saved key.
• `action` fails in a script or agent: non-interactive runs need --yes.
• A command or flag isn't recognized: check insightfulpipe --version. Commands such as use and the --table flag need version 0.2.0 or later; update with npm install -g insightfulpipe@latest.
• "This action is disabled for this connected account. An owner or admin must enable it for the account.": an owner, administrator or operator can turn it on in Configure actions for this account.
• "This account is connected read-only, so this action cannot be enabled for it. An owner or admin must reconnect it with Read & Write permissions.": reconnect the account with Read + Write.
• "Your role does not have permission to execute write actions. Only operators, admins, and owners can execute write operations.": members with the User role can only run reads.
• Wrong or missing IDs: run accounts --platform <platform> again and copy the IDs it returns.

FAQ

Should I use the CLI or an MCP server?

Use an MCP server in chat apps such as Claude, ChatGPT and Cursor, where you add a hosted URL and sign in. Use the CLI for terminal agents, scripts and scheduled jobs that need JSON output. Both reach the same connected accounts with the same permissions.

Does the CLI need an MCP server?

No. The CLI calls InsightfulPipe directly with your API key. You don't need to add an MCP server to use it.

Which version do I have?

Run insightfulpipe --version. The latest release on npm is 0.2.0.

Related

• InsightfulPipe CLI overview
• insightfulpipe on npm
• Unified MCP Server
• Claude Code Setup
• Codex CLI Setup
• Roles and Permissions