polkadata CLI

The command-line client for the polkadata SaaS — the service that watches a Google Drive, Dropbox, Box, or OneDrive folder and POSTs signed webhook events (file.created / file.modified / file.deleted) to your URL whenever files in it change.

The CLI is built for developers and AI agents: polkadata login is a reference client of the server's auth.md agent-registration protocol, and every command answers with machine-readable JSON on stdout (progress and prompts go to stderr).

Install

npm install          # from this directory
npm run build
npm link             # puts `polkadata` on your PATH

Requires Node.js ≥ 20.

Quickstart

# 1. Register / sign in — prints a link and a 6-digit code. Open the link,
#    sign in (WorkOS AuthKit: Google, GitHub, or email magic link — a new
#    account provisions itself), and type the code into the polkadata page.
polkadata login --email [email protected]

# 2. Create a grant for a provider account and open the authorize_url it
#    returns (that step is the cloud provider's OAuth consent).
polkadata grants create --provider dropbox

# 3. Watch a folder (the grant must be active; the first connection needs a
#    subscription — a 7-day free trial starts at <server>/billing).
polkadata connections create --grant grant_… --folder /docs \
  --webhook-url https://yourapp.example/hooks/polkadata

# Your webhook URL now receives signed file.* events.
polkadata connections deliveries conn_…   # inspect delivery state

How login works (auth.md)

polkadata login discovers the server's registration surface from its /.well-known/oauth-protected-resource + /.well-known/oauth-authorization-server metadata, registers with service_auth (your email), and shows you a verification_uri and a 6-digit code. You sign in on the polkadata page and type the code; the CLI polls until you finish and receives a durable polkadata API key (sk-…), saved to ~/.config/polkadata/config.json (mode 0600). The key is delivered exactly once; polkadata logout revokes it server-side (RFC 7009) and deletes the local copy.

Commands

| Command | What it does | | --- | --- | | login --email <e> [--server <url>] [--no-open] | Register/sign in; saves the API key | | logout | Revoke the saved key and forget it | | whoami | Show the tenant the key acts on | | providers | List providers configured on the server | | grants create --provider <p> | p = google_drive / dropbox / box / onedrive; prints the authorize_url | | grants list / get <id> / authorize <id> / delete <id> [--yes] | Manage grants | | connections create --grant <id> --webhook-url <url> [--folder <spec>] [--secret <s>] | Watch a folder (secret defaults to a generated whsec_…) | | connections list / get <id> / delete <id> [--yes] | Manage connections | | connections files <id> [--page-token <t>] [--page-size <n>] | List the folder's current files (initial sync) | | connections deliveries <id> [--limit <n>] | Delivery state for the connection's events | | keys create --label <l> / list / delete <id> [--yes] | Manage additional API keys |

Global flags: --server <url> and --key <sk-…> override everything; then POLKADATA_SERVER / POLKADATA_API_KEY; then the saved login. With nothing set, the server defaults to https://api.polkadata.ai.

Development

npm run build   # tsc → dist/
npm test        # compiles + runs node:test suites against a fake server

Zero runtime dependencies, on purpose.