Skip to content

docs: rewrite README with complete command reference #13

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nictuku merged 2 commits into from
Mar 29, 2026
Merged

docs: rewrite README with complete command reference #13

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ea1394c
docs: rewrite README with complete command reference
nictuku Mar 29, 2026
580c259
docs: focus intro on convenience over internals
nictuku Mar 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
303 changes: 272 additions & 31 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,15 @@
# pipeboard-cli

Command-line tool for managing Meta Ads, Google Ads, and TikTok Ads from your terminal. Built for AI agents and automation — authenticate once, connect your ad platforms via OAuth, and let your agents manage campaigns, pull reports, and optimize ads across platforms.
Manage Meta Ads and Google Ads from your terminal. Single binary, zero dependencies, 50ms startup.

Works as an alternative to [Pipeboard](https://pipeboard.co)'s MCP servers for agents that prefer CLI tools. Pipeboard gives you control over which ad accounts the CLI can access, and you can create API tokens scoped to specific accounts and commands.
Built for AI coding agents (Claude Code, Cline, OpenClaw) and automation scripts. No need to register apps with each ad platform, run your own MCP servers, or maintain brittle API scripts — authenticate once with [Pipeboard](https://pipeboard.co) and go.

## Why use the CLI

- **All platforms, one binary** — Meta Ads and Google Ads without configuring separate MCP servers
- **More tools than local MCP** — 117 commands covering campaigns, creatives, audiences, reporting, and more
- **Fast for agents** — sub-50ms cold start. Agents shell out to `pipeboard` instead of implementing MCP JSON-RPC
- **Scriptable** — pipe JSON output into `jq`, chain commands in bash, run from CI

## Installation

Expand All @@ -20,7 +27,7 @@ go install github.com/pipeboard-co/pipeboard-cli@latest

### Binary download

Download the latest release from [GitHub Releases](https://github.com/pipeboard-co/pipeboard-cli/releases).
Download from [GitHub Releases](https://github.com/pipeboard-co/pipeboard-cli/releases). Builds for macOS (arm64/amd64), Linux (arm64/amd64), and Windows (amd64).

## Authentication

Expand All @@ -36,7 +43,7 @@ Or store it in the config file:
pipeboard config set token <your-token>
```

Get your API token at [pipeboard.co/settings](https://pipeboard.co/settings).
Get your API token at [pipeboard.co/api-tokens](https://pipeboard.co/api-tokens).

### Browser OAuth (interactive)

Expand All @@ -46,52 +53,286 @@ pipeboard login

## Quick Start

After authenticating, fetch the available tools:

```bash
pipeboard refresh
```

This downloads tool definitions from Pipeboard's MCP servers and caches them locally at `~/.pipeboard/tools-cache.json`. Run this once after install, or again when new tools are available.

## Usage

Commands are auto-generated from Pipeboard's MCP tool definitions. Each ad platform is a top-level command with subcommands for every available operation.

```bash
# List Google Ads campaigns
pipeboard google-ads get-campaigns --customer-id 1234567890

# Execute a raw GAQL query
pipeboard google-ads execute-gaql-query --customer-id 1234567890 --query "SELECT campaign.id, campaign.name FROM campaign LIMIT 10"

# Get Meta Ads campaign insights
pipeboard meta-ads get-insights --object-id act_123 --date-preset last_30d

# Create a Meta Ads campaign
pipeboard meta-ads create-campaign --account-id act_123 --name "Spring Sale" --objective OUTCOME_SALES

# See all available commands for a platform
# See all available commands
pipeboard google-ads --help
pipeboard meta-ads --help

# Check version
pipeboard version
```

Flags are generated from each tool's JSON Schema — required flags are enforced and enum values are shown in help text.

## Development
## Commands

### Google Ads

50 commands across campaigns, ad groups, ads, keywords, audiences, extensions, and reporting.

#### Campaigns

| Command | Description |
|---------|-------------|
| `create-campaign` | Create a new campaign |
| `get-campaigns` | List campaigns |
| `get-campaign-metrics` | Get campaign performance metrics with optional time-series |
| `update-campaign` | Update campaign name, status, or budget |
| `enable-campaign` | Enable a paused campaign |
| `pause-campaign` | Pause a campaign |
| `create-pmax-campaign` | Create a complete Performance Max campaign with assets |
| `get-pmax-asset-groups` | Get asset groups for a Performance Max campaign |
| `update-pmax-asset-group` | Add/remove assets and search themes in a PMax asset group |

#### Ad Groups

| Command | Description |
|---------|-------------|
| `create-ad-group` | Create a new ad group in a campaign |
| `get-ad-groups` | List ad groups |
| `get-ad-group-metrics` | Get ad group performance metrics |
| `update-ad-group` | Update ad group name, status, or bids |

#### Ads

| Command | Description |
|---------|-------------|
| `create-responsive-search-ad` | Create a Responsive Search Ad (RSA) |
| `get-ads` | List ads |
| `get-ad-metrics` | Get ad performance metrics |
| `enable-ad` | Enable a paused ad |
| `pause-ad` | Pause an ad |

#### Keywords

| Command | Description |
|---------|-------------|
| `add-keywords` | Add keywords to an ad group |
| `get-keywords` | List keywords |
| `get-keyword-metrics` | Get keyword performance metrics |
| `enable-keyword` | Enable paused keywords |
| `pause-keyword` | Pause keywords |
| `update-keyword-bid` | Update CPC bid for keywords |
| `remove-keywords` | Remove keywords from an ad group |
| `add-negative-keywords` | Add negative keywords to a campaign or ad group |
| `get-negative-keywords` | List negative keywords |
| `remove-negative-keywords` | Remove negative keywords |

#### Audiences & Targeting

| Command | Description |
|---------|-------------|
| `add-audience-to-campaign` | Add an audience to a campaign |
| `get-audiences` | List available audience segments |
| `get-device-performance` | Performance breakdown by device type |
| `get-geo-performance` | Performance breakdown by location |
| `get-hour-of-day-performance` | Performance breakdown by hour of day |
| `get-search-terms-report` | Actual search queries that triggered ads |
| `update-network-settings` | Update network targeting (Search, Display, etc.) |

#### Extensions

| Command | Description |
|---------|-------------|
| `create-callout` | Create a callout extension |
| `create-sitelink` | Create a sitelink extension |
| `create-structured-snippet` | Create a structured snippet extension |
| `get-extensions` | List ad extensions for campaigns |
| `remove-extension` | Remove an extension from a campaign |
| `update-extension-status` | Enable or pause an extension |

#### Assets

| Command | Description |
|---------|-------------|
| `list-assets` | List creative assets in an account |
| `upload-asset` | Upload an image, text, or YouTube video asset |

#### Account & Reporting

| Command | Description |
|---------|-------------|
| `get-account-info` | Get account details |
| `list-customers` | List accessible customer accounts |
| `execute-gaql-query` | Run a raw GAQL query |
| `execute-mutate` | Run a raw mutate operation |
| `query-api-docs` | Search Google Ads API documentation |
| `create-email-report` | Send an AI-powered email performance report |
| `submit-feedback` | Report a bug or request a feature |

---

### Meta Ads

67 commands across campaigns, ad sets, ads, creatives, audiences, lead gen, and reporting.

#### Campaigns

| Command | Description |
|---------|-------------|
| `create-campaign` | Create a new campaign |
| `get-campaigns` | List campaigns |
| `get-campaign-details` | Get detailed campaign info |
| `update-campaign` | Update campaign settings |
| `duplicate-campaign` | Duplicate a campaign with all ad sets and ads |
| `bulk-update-campaigns` | Update multiple campaigns at once |
| `create-budget-schedule` | Schedule budget changes for a campaign |

#### Ad Sets

| Command | Description |
|---------|-------------|
| `create-adset` | Create a new ad set |
| `get-adsets` | List ad sets |
| `get-adset-details` | Get detailed ad set info |
| `update-adset` | Update ad set settings, budgets, and frequency caps |
| `duplicate-adset` | Duplicate an ad set with its ads |
| `bulk-update-adsets` | Update multiple ad sets at once |

#### Ads

| Command | Description |
|---------|-------------|
| `create-ad` | Create an ad with an existing creative |
| `get-ads` | List ads |
| `get-ad-details` | Get detailed ad info |
| `update-ad` | Update ad settings |
| `duplicate-ad` | Duplicate an ad |
| `bulk-update-ads` | Update multiple ads at once |

#### Creatives

| Command | Description |
|---------|-------------|
| `create-ad-creative` | Create a creative from an image or video |
| `create-carousel-ad-creative` | Create a carousel creative with multiple cards |
| `get-ad-creatives` | Get creative details for an ad |
| `get-creative-details` | Get creative details by creative ID |
| `get-ad-previews` | Get an ad or creative preview (iframe HTML) |
| `update-ad-creative` | Update creative name or optimization settings |
| `duplicate-creative` | Duplicate a creative |
| `bulk-create-ad-creatives` | Create multiple creatives in a batch |
| `bulk-get-ad-creatives` | Fetch creative details for multiple ads |

#### Media

| Command | Description |
|---------|-------------|
| `upload-ad-image` | Upload an image for use in creatives |
| `get-ad-image` | Download and visualize an ad image |
| `upload-ad-video` | Upload a video for use in creatives |
| `get-ad-video` | Get video details and source URL |
| `bulk-upload-ad-images` | Upload multiple images at once |
| `bulk-upload-ad-videos` | Upload multiple videos at once |

#### Audiences & Targeting

| Command | Description |
|---------|-------------|
| `create-custom-audience` | Create a custom audience |
| `create-lookalike-audience` | Create a lookalike audience from a seed |
| `get-custom-audiences` | List custom audiences |
| `delete-custom-audience` | Delete a custom audience |
| `add-users-to-audience` | Upload a customer list to an audience |
| `estimate-audience-size` | Estimate reach for targeting specs |
| `search-interests` | Search interest targeting options |
| `get-interest-suggestions` | Get suggestions based on existing interests |
| `bulk-search-interests` | Search interests across multiple keywords |
| `search-behaviors` | List behavior targeting options |
| `search-demographics` | List demographic targeting options |
| `search-geo-locations` | Search geographic targeting locations |

#### Insights & Reporting

| Command | Description |
|---------|-------------|
| `get-insights` | Get performance insights for any object |
| `bulk-get-insights` | Get insights for multiple objects at once |
| `create-email-report` | Send an AI-powered email performance report |
| `list-email-reports` | List email report schedules |
| `update-email-report` | Update an email report schedule |
| `delete-email-report` | Delete an email report schedule |

#### Account & Pages

| Command | Description |
|---------|-------------|
| `get-ad-accounts` | List accessible ad accounts |
| `get-account-info` | Get account details |
| `get-account-pages` | Get pages associated with an account |
| `get-instagram-accounts` | Get Instagram accounts for an ad account |
| `get-pixels` | List Meta pixels for an account |
| `search-pages-by-name` | Search for pages by name |

#### Lead Generation

| Command | Description |
|---------|-------------|
| `create-lead-gen-form` | Create a lead gen form on a Page |
| `get-lead-gen-forms` | List lead gen forms for a Page |
| `publish-lead-gen-draft-form` | Publish a draft lead gen form |
| `update-lead-gen-form-status` | Archive or reactivate a form |

#### Product Catalogs

| Command | Description |
|---------|-------------|
| `list-catalogs` | List product catalogs for an account |
| `list-product-sets` | List product sets in a catalog |

#### Other

| Command | Description |
|---------|-------------|
| `submit-feedback` | Report a bug or request a feature |

## How It Works

```bash
# Build
make build
```
pipeboard <platform> <command> [flags]
│
▼
MCP JSON-RPC client (HTTP POST)
│
▼
https://mcp.pipeboard.co/<server>
│
▼
Meta / Google APIs
```

The CLI is a thin client. All API calls go through Pipeboard's cloud — auth tokens, rate limiting, and logging are handled server-side. This is why the CLI repo contains no secrets and can be fully open-source.

## Also Available: MCP Servers

If you prefer MCP over CLI, Pipeboard offers remote MCP servers for the same platforms:

# Run tests
make test
| Platform | Remote MCP URL |
|---|---|
| Meta Ads | `https://mcp.pipeboard.co/meta-ads-mcp` |
| Google Ads | `https://mcp.pipeboard.co/google-ads-mcp` |

# Install locally
make install
Works with Claude Pro/Max, Cursor, and any MCP client. Set up at [pipeboard.co](https://pipeboard.co).

## Community

- [Discord](https://discord.gg/YzMwQ8zrjr) — join the community
- [Email](mailto:info@pipeboard.co) — support and questions
- [Issues](https://github.com/pipeboard-co/pipeboard-cli/issues) — bug reports and feature requests

## Development

```bash
make build # Build binary to bin/pipeboard
make test # Run tests
make install # Install to $GOPATH/bin
make lint # Run go vet
```

## License
Expand Down
Loading