Gaql
Execute a GAQL (Google Ads Query Language) query
AI Agents CLInpm · v0.2.0·Node.js 18+
Marketing data CLI
for autonomous AI agents
Query and manage 45 marketing platforms from the terminal. Built for Claude Code, Codex, OpenClaw and any agent that can run a shell command.
$ npm install -g insightfulpipeRuns wherever your agent runs
Claude Code
Codex
Gemini CLI
OpenClaw
Cursor
Hermes- Windsurf
- Zed
- OpenCode
- n8n
$ insightfulpipe auth
Install, authenticate, and start querying
You need Node.js 18 or later and an InsightfulPipe workspace with at least one connected account. Four steps, about two minutes.
- 01
Install the package
Install insightfulpipe globally from npm. It adds the insightfulpipe command to your PATH.
npm install -g insightfulpipe# Node.js 18 or later$ npm install -g insightfulpipe - 02
Create an API key
In the InsightfulPipe app, open Settings > API Keys and create a key. Keys start with ip_sk_ and belong to one workspace.
app.insightfulpipe.com/settings/api-keysSettingsAPI KeysCreate keyWorkspace API keys
Keys belong to this workspace only.
Claude Code · laptopnewip_sk_live_9f3a••••••••••••4c1eCopyCI pipelineip_sk_live_72bd••••••••••••a0f73 days agoShown once. Paste it into
insightfulpipe authin the next step. - 03
Save the key
Run insightfulpipe auth and paste the key. It is stored in your operating system keyring, or in ~/.insightfulpipe/config.json if you pass --insecure-storage.
insightfulpipe auth$ insightfulpipe auth? Paste your API key (ip_sk_...): ********✓ Saved to keyring - 04
Check the connection
Run insightfulpipe doctor to check the token, API URL and connectivity, then insightfulpipe whoami to see your workspaces.
insightfulpipe doctor$ insightfulpipe doctor✓ token · api url · connectivity$ insightfulpipe whoami[email protected] · 2 workspaces Run your first query
Pull the last 30 days of Google Ads campaigns. Every read follows the same pattern: a platform slug plus a JSON body, JSON back. Use action instead of query for writes such as creating or pausing a campaign.
insightfulpipe query google-ads$ insightfulpipe query google-ads -b '{ "action": "get_campaigns", "workspace_id": 123, "brand_id": 456, "account_id": "1234567890", "date_range": "LAST_30_DAYS" }'{ "status": "success", "data": [ { "campaign": "Brand - Shoes", "clicks": 1840, "cost": 7580.80 }, { "campaign": "Search - Sale", "clicks": 3120, "cost": 7425.60 } ] }
$ insightfulpipe action --help
Writes follow your account action controls
The CLI gets no extra permissions. Every call goes through the same checks as the MCP servers, configured per connected account in the InsightfulPipe app. Flip a switch below and watch the terminal follow.
In the app · try the switches
app.insightfulpipe.com/accounts/1234567890/actions
AccountsGoogle AdsAcme Store
Action controls
account 1234567890 · workspace 123
Connection
Read-only connections can enable read actions only.
Actions exposed to agents
3 of 12 enabled
Reads
gaqlRun a GAQL reportonWrites
pause_adPause an adonremove_keyworddestructiveDelete a keywordoff9 more actions not shown
Saved · applies to the CLI and MCP serversRestricted members: reads only
In the terminal · what the agent gets
insightfulpipe · workspace 123
# Reads work on any connection$ insightfulpipe query google-ads -b '{"action":"gaql", …}'{ "status": "success", "data": [ … ], "meta": { … } }# A write asks before it runs$ insightfulpipe action google-ads -f pause-ad.json? Execute write action "pause_ad" on "google-ads"? [y/N] y✓ pause_ad applied · ad 987654 is now PAUSED# Agents and scripts confirm with --yes$ insightfulpipe action google-ads -f remove-keyword.json --yes✗ remove_keyword is disabled for account 1234567890 (exit 1)Same switches as the MCP servers. Change them once in the app; both interfaces obey.
- 01
query for reads, action for writes
Use query for reports and listings. Use action for creates, updates and deletes; it asks for confirmation unless you pass --yes.
- 02
Actions on or off per account
Owners, admins and operators choose which actions each connected account exposes to agents. Disabled actions are hidden from helper and blocked if called.
- 03
Read-only or Read & Write
Accounts connect as Read-only or Read & Write. On a Read-only connection, only read actions can be enabled.
- 04
Destructive actions off by default
Actions flagged as destructive, such as deletes, stay off until an owner, admin or operator turns them on for the account.
- 05
Restricted members get reads only
Restricted team members can only use the accounts they are granted, and only the read actions enabled on them.
- 06
Workspace-scoped API keys
Each API key belongs to a single workspace, so an agent using it cannot reach accounts in another workspace.
Actions
Available Actions
1929 actions available across all 45 connected platforms.
Select a platform to view its actions
Google Ads Actions
87 actions available·google-ads
Read Actions (28)
Generate Keyword Ideas
Generate keyword ideas from seed keywords or URL using Keyword Planner
Get Account Info
Customer account information and settings
Get Ad Group Bidding
Ad group bidding strategy information
Get Ad Group Labels
Ad group label associations
Get Ad Groups
Ad group performance data and configuration
Get Ad Labels
Ad group ad label associations
Get Ads
Ad creative performance data and policy information
Get Audiences
Audience targeting and demographic performance data
Write Actions (59)
Add Audience Targeting
Target a user list (remarketing audience) with an ad group
Add Call Asset
Add a phone call asset to the account (shows phone number with ads)
Add Callout Asset
Add callout text snippets to a campaign (e.g., 'Free Shipping', '24/7 Support')
Add Demographic Targeting
Add age and/or gender demographic targeting to an ad group
Add Dsa Webpage Targeting
Add a webpage-targeting criterion to a DSA ad group (incl. page-feed label targeting)
Add Keywords
Add keywords to an ad group
Add Label
Create a new label for organizing campaigns, ad groups, and ads
Add Lead Form Asset
Add a lead form to a campaign (users submit info directly from the ad)
Add Location Targeting
Add geographic location targeting to a campaign (countries, cities, postal codes, regions)
$ insightfulpipe --help
Every command, one reference
Twelve commands cover setup, discovery and execution. Pick one to see its usage, options and an example.
insightfulpipe auth --helpv0.2.0
Setup
Discover
Run
Defaults
$ insightfulpipe auth --help
Usage
insightfulpipe auth [--insecure-storage]
Prompts for an API key and stores it in your OS keyring. When INSIGHTFULPIPE_TOKEN is set, the CLI uses it instead and you can skip this step.
Options
- --insecure-storage
- Write the key to ~/.insightfulpipe/config.json instead of the keyring
Example
$ insightfulpipe auth? Paste your API key (ip_sk_...): ********✓ Saved to keyringEvery command accepts --help.readwrite
HAVE QUESTIONS?