Polymetrics CLI

One CLI to rule them all.

pm is a local-first data CLI for ETL, embedded DuckDB SQL, reverse ETL, scheduling, and AI-agent-safe automation. It runs as one Go binary, keeps credentials local, and speaks JSON everywhere.

Website · Docs · Quickstart · Agent Contract · Contributing

Polymetrics turns the whole operational data loop into a command-line workflow:

source -> extract -> local warehouse -> DuckDB SQL -> plan -> preview -> approve -> write back

No hosted control plane is required for the first useful run. Use it on a laptop, in CI, in cron, in a container, or inside an LLM agent pod with the same command surface.

Build from source:

git clone https://github.com/polymetrics-ai/cli
cd cli
make build
./pm version

Run a local extract and query loop with the sample connector:

export PM_SAMPLE_TOKEN=demo

./pm init
./pm credentials add sample --connector sample --from-env token=PM_SAMPLE_TOKEN
./pm credentials add warehouse --connector warehouse --config path=.polymetrics/warehouse
./pm connections create demo \
  --source sample:sample \
  --destination warehouse:warehouse \
  --stream customers \
  --primary-key id \
  --cursor updated_at \
  --table customers

./pm etl run --connection demo --stream customers --json
./pm query run --table customers --limit 5 --json

Release binaries are published on GitHub:

gh release download --repo polymetrics-ai/cli --pattern 'pm_*_darwin_arm64.tar.gz'

Windows is not a release target. The published release matrix is Linux and macOS; Windows can return only with a customer ask and the complete build, verification, and release path restored together.

Data work is usually split across a pipeline service, a warehouse, a reverse ETL product, a scheduler, and a separate automation interface. Polymetrics puts the developer loop first: install one binary, connect a source, inspect data, run SQL, then write back only after an explicit approval step.

This makes the tool useful for:

• Developers who want local-first ETL without provisioning infrastructure.
• Data engineers who need reproducible extract, query, and reverse ETL flows.
• AI agents that need a stable CLI contract instead of brittle prose parsing.
• Open-source contributors who want connector work to be small and testable.

Polymetrics is designed for humans and LLM agents to drive the same commands.

pm etl run --connection github --stream issues --json
pm query run --sql "select * from issues where state = 'open'" --json
pm reverse plan sync --source-table stale_issues --destination github:write --json

The contract is intentionally boring:

• --json returns versioned envelopes on stdout.
• Progress and logs go to stderr.
• Exit codes separate usage, validation, auth, connector, runtime, policy, and internal failures.
• Reverse ETL is split into plan, preview, approve, and run.
• Secrets are referenced by field name and never printed.

Use the CLI to inspect what is available in your binary and what is planned in the catalog:

pm connectors list
pm connectors list --all
pm connectors inspect github --json
pm connectors port-plan --all --json

The catalog contains declared and runtime-enabled connector entries. Enabled support is definition-bundle first, interpreted by the declarative engine, with typed hooks or native implementations only where the documented contract needs them. Runtime-visible support comes from pm connectors inspect, not a catalog filename or a generated manual.

Every connector flow is mediated by the local warehouse: API → warehouse → API, API → warehouse → database, database → warehouse → API, or database → warehouse → database. There are currently zero accepted live certifications; fixtures, endpoint ledgers, and certification.json files are not live proof. See the connector delivery canon before implementing or certifying a connector.

flowchart LR
  CLI["pm CLI / agent"] --> SRC["Sources"]
  SRC --> WH[("Local warehouse")]
  WH --> SQL["DuckDB SQL"]
  SQL --> PLAN["Plan and preview"]
  PLAN --> DEST["Destinations"]

• internal/connectors contains per-system connector packages.
• internal/app owns ETL, query, reverse ETL, scheduling, and automation flows.
• cmd/pm exposes the CLI.
• docs contains generated manuals and connector documentation.
• website publishes the docs, connector catalog, blog, llms.txt, and sitemap.

The canonical description is:

Polymetrics CLI is a local-first data CLI for single-binary ETL, embedded DuckDB SQL, reverse ETL, connector automation, and AI agent data workflows.

The README, docs, website metadata, blog, sitemap, and llms.txt use the same terms deliberately so humans, search engines, and AI answer engines can identify the project without keyword stuffing.

Canonical topics:

• local-first data CLI
• single-binary ETL
• embedded DuckDB SQL engine
• reverse ETL CLI
• AI agent data workflows
• connector catalog
• approval-gated writes

Connector PRs are the best first contribution. Start with docs/connector-canon/IMPLEMENTATION-PROCEDURE.md and docs/migration/conventions.md, complete the Foundation Check, add focused tests, and run verification before opening a PR.

make verify
make verify-duckdb

Use Conventional Commits:

• fix(github): handle paginated issue labels
• feat(connector): add linear
• docs(readme): clarify local-first quickstart

• Local CLI runtime
• JSON output and stable exit-code contract
• Local encrypted credential vault
• ETL, query, and approval-gated reverse ETL
• Release binaries
• Website docs, connector catalog, blog, sitemap, and llms.txt
• More connector capability work after its typed foundations and live proof exist
• Homebrew tap
• Bundled MCP server
• Hosted examples and reproducible benchmark datasets

Polymetrics uses an explicit path-based license boundary:

The permissive definitions license is intended to make connector catalog contributions and reuse straightforward. The engine, CLI, website, and other core code remain AGPL. See LICENSING.md for the complete path map, contribution terms, and third-party boundaries.

The AGPL permits commercial use subject to its conditions. Organizations that need different terms may contact Polymetrics AI about a separate written agreement; this repository does not itself grant a commercial license.