pipiads-cli

CLI for the Pipiads Open API.

Requirements

• Node.js 20+
• A Pipiads Open API key

Install

Global install:

npm install -g pipiads-cli
pipiads --help

Run without installing globally:

npx pipiads-cli --help

Setup

Before using the CLI:

• Visit the official Pipiads website at https://pipiads.com/ to view real-time dashboard data and explore the product UI.
• Visit https://www.pipispy.com/ to get your API key and manage billing or recharges.
• Set your API key as an environment variable:

export PIPIADS_API_KEY=<KEY>

Quick start

pipiads advertiser detail --id 66f994b3a8f1cc723674b9ff

Show the installed CLI version:

pipiads --version

Authentication

API commands require an API key.

Two supported ways:

Pass the key on each command:

pipiads advertiser detail --key <KEY> --id 66f994b3a8f1cc723674b9ff

Or use an environment variable:

export PIPIADS_API_KEY=<KEY>
pipiads advertiser detail --id 66f994b3a8f1cc723674b9ff

--key takes precedence over PIPIADS_API_KEY.

If neither is provided, the CLI prints:

Missing API key. Pass --key or set PIPIADS_API_KEY.

Command structure

Commands are grouped by domain:

pipiads <domain> <command> [options]

Examples of domains:

• ad-monitor-task
• advertiser
• app
• product
• store
• ad-library
• ai-search-image
• reference

Use help at any level:

pipiads --help
pipiads advertiser --help
pipiads advertiser detail --help

Output and exit codes

Successful responses are written to stdout as JSON.

Compact output by default:

pipiads advertiser detail --key <KEY> --id 66f994b3a8f1cc723674b9ff

Pretty output:

pipiads advertiser detail --key <KEY> --id 66f994b3a8f1cc723674b9ff --pretty

Errors are written to stderr.

Exit codes:

• 0 success
• 1 unknown error
• 2 invalid command or arguments
• 3 missing API key
• 4 network or HTTP error
• 5 Pipiads API error

API transport behavior

The CLI routes commands to the documented Pipiads Open API transports:

• monitor-data commands -> https://www.pipispy.com/open-api/v1/monitor/data
• data commands -> https://www.pipispy.com/open-api/v1/data
• upload commands -> https://www.pipispy.com/open-api/v1/upload-file

You can override the base URL when needed:

pipiads advertiser detail --key <KEY> --id 66f994b3a8f1cc723674b9ff --base-url https://example.com/open-api/v1/data

Examples

Advertiser detail

pipiads advertiser detail --key <KEY> --id 66f994b3a8f1cc723674b9ff

Advertiser rank list

pipiads advertiser rank-list --key <KEY> --current-page 1 --page-size 10

App list

pipiads app list \
  --key <KEY> \
  --current-page 1 \
  --page-size 10 \
  --plat-type 1 \
  --search-type 1 \
  --sort 1 \
  --sort-type desc \
  --time 7

Product list

pipiads product list --key <KEY> --plat-type 1 --search-type 1 --keyword garden

Store rank list

pipiads store rank-list \
  --key <KEY> \
  --data-type 0 \
  --time 7 \
  --sort 0 \
  --sort-type desc \
  --page-size 20 \
  --current-page 1

Monitor task ad details

pipiads ad-monitor-task ad-details --key <KEY> --ad-id 1160096586185797

Create monitor task

pipiads ad-monitor-task create-monitor-task \
  --key <KEY> \
  --facebook-page-id-list 614178972053891,714739975064116

Comma-separated values are converted into arrays before the request is sent.

Image upload usage

Upload a local image file:

pipiads ai-search-image submit-file --key <KEY> --image-file ./example.jpg

Submit an image URL:

pipiads ai-search-image submit-url --key <KEY> --image-url https://example.com/image.jpg

AI agent usage

This package is published as a CLI. The supported integration path for agents is shell execution.

Examples:

pipiads advertiser detail --id 66f994b3a8f1cc723674b9ff
pipiads product list --plat-type 1 --search-type 1 --keyword garden

Recommended contract for automation:

• read successful JSON from stdout
• read human-readable errors from stderr
• branch on the process exit code

Reference commands

Some docs are reference-only and do not map to executable API endpoints. Those commands are still exposed under the reference domain so the CLI catalog stays aligned with the docs.

Example:

pipiads reference region --pretty

That prints metadata describing the source documentation file.

Error behavior

The CLI is designed to show actionable help:

• unknown commands print top-level help
• command validation errors print the error and the matching command help
• missing API keys explain both supported auth methods

Examples:

pipiads advertiser detail
pipiads ai-search-image submit-file
pipiads unknown-domain

Development

Install dependencies:

npm install

Run locally during development:

npm run dev -- --help

Run tests:

npm test

Build:

npm run build

Dry-run package contents:

npm pack --dry-run

Publishing readiness

Current package safeguards:

• compiled CLI binary in dist/
• files whitelist for publish output
• prepublishOnly runs build and tests before publish

Documentation source

The command catalog is derived from the API markdown docs in the API documentation directory used for this project. The CLI maps those docs into grouped commands, help text, and request metadata.