ppspy-cli

A Node.js CLI for PPSPY Open Platform APIs.

It uses package-internal command metadata from generated/commands.json to execute live API requests for endpoint commands. Pure reference docs such as enum lists remain local reference commands.

Requirements

• Node.js 20+
• A PPSPY API key

Install

Local development

npm install
npm test

Package-style local verification

npm install
npm test
npm pack
npm install -g ./ppspy-cli-0.1.1.tgz
ppspy help

Run directly from the repo

node ./bin/ppspy.js help

Authentication

Visit the official website at ppspy.com to view real-time dashboard data and product UI.

Visit the direct API site at api.ppspy.com to get your API key and manage billing/recharge.

Set the environment variable:

export PPSPY_API_KEY=your_api_key

You can also pass the key explicitly:

ppspy ad-filter-options list --api-key your_api_key

Flag precedence:

• --api-key overrides PPSPY_API_KEY

Optional base URL override for testing:

export PPSPY_BASE_URL=http://127.0.0.1:3000

Usage

List domains and commands:

ppspy help

Show help for a domain:

ppspy shopify-store --help

Show help for a command:

ppspy shopify-store details --help

Run endpoint commands:

ppspy ad-filter-options list
ppspy shopify-store details --id 123
ppspy ad-monitor create-group --name Popular

Run a reference command:

ppspy reference ad-e-commerce-platform-list

Parameter conventions

• CLI parameters use --field value
• Path parameters map from doc placeholders like {id} to flags like --id
• Query parameters are appended to the request URL
• Body parameters are serialized as JSON
• Primitive values are coerced from doc types where supported, including integers, numbers, booleans, and null
• JSON-like values such as arrays or objects can be passed as JSON strings
• Nested body objects use flattened flag names derived from their path, such as --extend_keywords_field
• Repeated nested leaf names are disambiguated by prefixing the parent path in the flag name

Examples:

ppspy shopify-store details --id 123
ppspy ad-monitor-task list --page 1 --per_page 10
ppspy ad-monitor create-task --facebook_page_id_list '["100726615757315"]' --group_id d7fffb6c5166af6c285438ecf5202a87
ppspy ad-product list --extend_keywords_field product_name --extend_keywords_value shoe --extend_keywords_logic_operator and --page 2 --per_page 20

Error handling

• Missing API key returns a clear error
• Missing required command parameters return an error and print command help
• Non-2xx responses print the returned response body when available
• --help on a command shows whether it is a live API command or local reference data

Development

The package ships with generated command data in generated/commands.json, so normal development, testing, and packaging do not require any external markdown docs.

Run tests:

npm test

Run packaging smoke check:

npm run pack:check

Run the CLI locally:

node ./bin/ppspy.js help

If you need to refresh the generated command data manually for maintenance work:

npm run build:commands

Publish preparation

Before publishing to npm, verify:

npm install
npm test
npm run pack:check
npm pack
npm install -g ./ppspy-cli-0.1.1.tgz

Then smoke-test a few commands locally:

ppspy help
ppspy shopify-store list --help
PPSPY_API_KEY=your_api_key ppspy ad-filter-options list

If you want to publish:

npm login
npm publish

Package metadata checklist

Before publishing, add these fields to package.json if you want npm package metadata to link back to your repository:

• repository.url
• homepage
• bugs.url

Notes

• Command behavior is driven by the package-internal generated/commands.json
• Enum/list commands are local reference outputs, not live API requests
• Release-grade support is strongest for common path/query/body shapes; very irregular nested request schemas may still need targeted follow-up handling