CLI

Ploid CLI reference

A lightweight command-line client for the Ploid Public API. Every command maps to a /v1 endpoint — the CLI handles config, stdin/file input, polling, and formatted output.

Quick start

Requires Node.js 20 or newer (plus npm, curl, and tar). The install script downloads the CLI source from github.com/ploidcom/cli, builds it, and links the ploid command globally.

curl https://ploid.com/install -fsS | bash

Prefer a package manager? Once @ploid/cliis published to npm, you'll be able to install it directly:

npm install -g @ploid/cli

npx @ploid/cli login

ploid login

The CLI prints a short code and opens https://ploid.com/auth/cli in your browser. Approve the device and an API key is saved to ~/.config/ploid/config.json.

# Look up one person
ploid people lookup --name "Jane Doe" --company "Acme"

# Reveal contact fields
ploid people enrich --linkedin-url https://www.linkedin.com/in/example \
  --fields profile,work_email,github

# Bulk enrich from a file and wait for completion
ploid batch create --file ./people.json --fields linkedin,github,work_email \
  --max-cost-usd 10 --wait

Authentication

Browser login is the easiest path — no manual key copy. Keys minted via login get full CLI scopes and expire after 90 days; run ploid login again to refresh. Use --no-browser on headless machines (the URL is printed instead).

ploid login
ploid logout       # revoke server-side and remove local config
ploid auth check   # validate the saved key and print balance

Manual API key

For CI or scripts, provide a key in order of precedence: --api-key flag, PLOID_API_KEY env var, or ~/.config/ploid/config.json. Create keys in Settings → API keys.

{
  "api_key": "ploid_live_...",
  "base_url": "https://api.ploid.com"
}

Account

ploid account credits
ploid account usage

Global flags

Available on every command.

Flag	Description
`--api-key`	API key (overrides env and config file).
`--base-url`	API base URL (default https://api.ploid.com).
`--json`	Emit raw JSON; agent chat streams newline-delimited JSON events.
`--quiet`	Suppress progress lines (printed to stderr).

Exit codes: 0 success, 1 usage/input error, 2 API error, 3 missing auth/config.

`ploid agent`

Stream the same workspace agent used by /workspace/new. Progress goes to stderr in human mode; add --json or --ndjson to emit machine-readable events for Claude, Codex, Cursor, and other coding agents.

ploid agent chat --query "find DevTools founders in SF"
ploid agent chat --query "find AI infra buyers" --model fast --json
ploid agent chat --query "continue the search" --session-id thread_abc123

Sub-agent progress is emitted as data-subagent stream events with angleId, mission, status, activity, and optional peopleFound. Use ploid people agent as a people-focused alias.

`ploid people`

ploid people search --query "founders in SF building AI sales tools" \
  --mode natural --size 50
ploid people lookup --name "Jane Doe" --company "Acme"
ploid people enrich --name "Jane Doe" --company "Acme" \
  --fields work_email,github,x
ploid people agent --query "the CTO of Ploid"

--filters accepts a JSON file (or - for stdin) with structured search filters. Use precise titles like Founder and Co-Founder — not Founders, which matches company names and assistants. For multi-part intent (role + topic + location), prefer --mode natural over table mode.

`ploid batch`

Bulk enrichment from a JSON array or JSONL file. Each row needs an identifier (LinkedIn URL, github:handle, etc.).

ploid batch estimate --file ./people.json --fields linkedin,github,work_email
ploid batch create --file ./people.json --fields linkedin,github,work_email \
  --webhook-url https://example.com/hook
ploid batch status batch_abc123
ploid batch results batch_abc123 --all
ploid batch wait batch_abc123

`ploid searches`

Async people-set searches — create, refine, and export results.

ploid searches create --query "Sales leaders at US fintechs" \
  --count 100 --include profile --wait
ploid searches list
ploid searches get peopleset_abc123
ploid searches items peopleset_abc123 --cursor 0 --limit 100
ploid searches refine peopleset_abc123 --query "only Series B+"
ploid searches export peopleset_abc123 --format csv --out results.csv

`ploid monitors`

ploid monitors list
ploid monitors create --people-set-id peopleset_abc123 --interval-days 7
ploid monitors delete monitor_abc123

`ploid webhooks`

ploid webhooks list
ploid webhooks create --url https://example.com/hook \
  --events batch.completed,people_set.completed
ploid webhooks delete webhook_abc123

`ploid linkedin`

LinkedIn data passthrough — list available endpoints and call them with key=value parameters.

ploid linkedin catalog
ploid linkedin call profile url=https://www.linkedin.com/in/example
ploid linkedin call profiles-search search="VP Engineering" locations="United States"

Scripting & pipes

Pipe JSONL into batch enrichment via stdin — use --file - or omit --file entirely:

cat people.jsonl | ploid batch create --fields github,x

Add --json on any command when you need raw JSON for jq or downstream tools. Agent chat uses newline-delimited JSON events so sub-agent updates can be consumed while the turn is still running. Progress lines go to stderr so stdout stays clean for pipes.

HTTP API

The CLI is a thin wrapper over api.ploid.com/v1. Run ploid openapi to print the full spec, or explore endpoints in the API playground (requires login).

Source and issue tracker: github.com/ploidcom/cli.