@customerio/cli 0.0.0-bootstrap → 0.0.2

package/.npm/run.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+
+const { spawnSync } = require("child_process");
+const { existsSync } = require("fs");
+const path = require("path");
+
+const pkgRoot = path.join(__dirname, "..");
+const rootPkg = require(path.join(pkgRoot, "package.json"));
+const optionalDependencies = rootPkg.optionalDependencies || {};
+const platform = (rootPkg.customerioCli?.platforms || []).find(
+  (candidate) => candidate.os === process.platform && candidate.cpu === process.arch
+);
+
+if (!platform) {
+  console.error(
+    `Unsupported platform for ${rootPkg.name}: ${process.platform}-${process.arch}`
+  );
+  process.exit(1);
+}
+
+const platformPackage = Object.keys(optionalDependencies).find((packageName) =>
+  packageName.endsWith(`-${platform.npm}`)
+);
+let platformPackageRoot;
+
+if (!platformPackage) {
+  console.error(
+    `Missing optional dependency metadata for ${process.platform}-${process.arch}.`
+  );
+  process.exit(1);
+}
+
+try {
+  platformPackageRoot = path.dirname(
+    require.resolve(`${platformPackage}/package.json`, { paths: [pkgRoot] })
+  );
+} catch {
+  console.error(
+    `Missing optional dependency ${platformPackage} for ${process.platform}-${process.arch}.\n` +
+      "Reinstall without disabling optional dependencies."
+  );
+  process.exit(1);
+}
+
+const binPath = path.join(platformPackageRoot, "bin", `cio${platform.ext || ""}`);
+
+if (!existsSync(binPath)) {
+  console.error(
+    `Missing ${rootPkg.name} binary at ${binPath}.\n` +
+      "Reinstall without disabling optional dependencies."
+  );
+  process.exit(1);
+}
+
+const result = spawnSync(binPath, process.argv.slice(2), {
+  stdio: "inherit",
+});
+
+if (result.error) {
+  console.error(result.error.message);
+  process.exit(1);
+}
+
+if (result.signal) {
+  try {
+    process.kill(process.pid, result.signal);
+  } catch {
+    // Some platforms cannot re-raise child signals; use a generic failure below.
+  }
+  process.exit(1);
+}
+
+process.exit(result.status ?? 1);

package/README.md

@@ -1,3 +1,222 @@
-# @customerio/cli
+# Customer.io CLI (`cio`)
 
-Bootstrap placeholder package for trusted publishing setup.
+An agent-first CLI for Customer.io APIs.
+
+**800+ Journeys routes + 100+ CDP Pipelines routes, zero per-endpoint code.** A single `cio api <path>` command covers every endpoint. Every command returns structured JSON to stdout. Every error returns structured JSON to stderr.
+
+AI agents are the primary consumer. Use `cio schema` to introspect endpoints before calling them.
+
+## Install
+
+```bash
+npm i -g @customerio/cli
+cio --help
+```
+
+To build from source instead:
+
+```bash
+go install github.com/customerio/cli@latest
+```
+
+## Install the agent skill
+
+This repo ships a [SKILL.md](skills/cio/SKILL.md) so Claude Code, Cursor, Codex, Windsurf, and other agents that support [open agent skills](https://github.com/vercel-labs/skills) know how to drive the CLI. Install it with:
+
+```bash
+npx skills add customerio/cli
+```
+
+## Authentication
+
+The CLI uses **service account tokens** (`sa_live_...`) for authentication. These are exchanged for short-lived JWTs via OAuth 2.0 client credentials, just like `gh auth`.
+
+### Login
+
+```bash
+# Interactive — prints the browser login URL, then prompts for the minted token
+cio auth login
+
+# Read from stdin (for CI/automation; login still auto-discovers region)
+echo "$SA_TOKEN" | cio auth login --with-token
+
+# Verify auth works
+cio auth status
+
+# Print raw token
+cio auth token
+
+# Logout
+cio auth logout
+```
+
+### Token Resolution Order
+
+1. `--token` flag (highest priority)
+2. `CIO_TOKEN` environment variable
+3. `~/.cio/config.json` file (lowest priority)
+
+When you use `CIO_TOKEN` or `--token` directly on normal commands, you may
+also need `CIO_REGION=us|eu` or `--api-url`.
+
+### How It Works
+
+1. You provide a `sa_live_...` token (from Customer.io UI → Account Settings → Manage API Credentials → Service Accounts)
+2. The CLI exchanges it for a JWT via `POST /v1/service_accounts/oauth/token`
+3. The JWT is cached locally and refreshed automatically when it expires
+4. All API calls use `Authorization: Bearer <jwt>`
+
+### Override per-command
+
+```bash
+cio --token sa_live_xxx api /v1/environments/{environment_id}/campaigns --params '{"environment_id": "123"}'
+CIO_TOKEN=sa_live_xxx cio api /v1/environments/{environment_id}/campaigns --params '{"environment_id": "123"}'
+```
+
+## Usage
+
+Use `cio api <path>` for any API endpoint. Path placeholders are resolved from `--params`. The HTTP method defaults to GET (or POST if `--json` is provided); override with `-X`:
+
+```bash
+# List campaigns in workspace 123
+cio api /v1/environments/{environment_id}/campaigns --params '{"environment_id": "123"}'
+
+# Get a specific campaign
+cio api /v1/environments/{environment_id}/campaigns/{campaign_id} \
+  --params '{"environment_id": "123", "campaign_id": "456"}'
+
+# Create a campaign
+cio api /v1/environments/{environment_id}/campaigns \
+  --params '{"environment_id": "123"}' \
+  --json '{"campaign": {"name": "Welcome Flow", "type": "none"}}'
+
+# Explicit method override
+cio api /v1/environments/{environment_id}/campaigns/{campaign_id} -X DELETE \
+  --params '{"environment_id": "123", "campaign_id": "456"}'
+
+# Introspect endpoints
+cio schema                          # list all resources
+cio schema campaigns                # list endpoints for a resource
+cio schema campaigns.list           # full schema for a method
+cio schema GET /v1/environments/{environment_id}/campaigns  # by HTTP method + path
+```
+
+### Account ID fallback
+
+Paths that include `{account_id}` auto-fill from the account ID stored during `cio auth login`, so you don't need to pass it on every call:
+
+```bash
+cio api /v1/accounts/{account_id}/environments
+```
+
+Pass `--params '{"account_id": "..."}'` to override, or set `CIO_ACCESS_TOKEN` to disable the fallback (the pre-exchanged JWT may belong to a different account).
+
+### Filtering with jq
+
+```bash
+# Filter with --jq to save context window
+cio api /v1/environments/{environment_id}/campaigns \
+  --params '{"environment_id": "123"}' \
+  --jq '.campaigns[] | {id, name, state}'
+
+# Complex filtering
+cio api /v1/environments/{environment_id}/campaigns \
+  --params '{"environment_id": "123"}' \
+  --jq '.campaigns[] | select(.state == "active") | {id, name}'
+```
+
+### Write operations
+
+```bash
+# Always dry-run first
+cio api /v1/environments/{environment_id}/campaigns \
+  --params '{"environment_id": "123"}' \
+  --json '{"campaign": {"name": "Welcome Flow", "type": "none"}}' --dry-run
+
+# Then execute (removes --dry-run)
+cio api /v1/environments/{environment_id}/campaigns \
+  --params '{"environment_id": "123"}' \
+  --json '{"campaign": {"name": "Welcome Flow", "type": "none"}}'
+```
+
+### Pagination
+
+```bash
+cio api /v1/environments/{environment_id}/campaigns \
+  --params '{"environment_id": "123"}' --page 2 --limit 50
+
+# Auto-paginate (emits NDJSON — one JSON object per line)
+cio api /v1/environments/{environment_id}/campaigns \
+  --params '{"environment_id": "123"}' --page-all
+```
+
+## Global Flags
+
+| Flag | Env Var | Description |
+|---|---|---|
+| `--token <value>` | `CIO_TOKEN` | Service account token override |
+| `-X, --method` | | HTTP method override (default: GET, or POST if --json) |
+| `--json <payload>` | | Raw JSON request body or `@filename` to read from file |
+| `--params <json>` | | Query parameters as JSON → query string |
+| `--jq <expr>` | | jq expression filter (via gojq) |
+| `--dry-run` | | Validate + print request, skip execution |
+| `--api-url <url>` | | API base URL override |
+| `--timeout <duration>` | `CIO_TIMEOUT` | HTTP request timeout (default: 30s) |
+| `--page <n>` | | Page number |
+| `--limit <n>` | | Page size |
+| `--page-all` | | Auto-paginate, emit NDJSON |
+
+## Exit Codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Success |
+| 1 | General error |
+| 2 | Validation / input error |
+| 3 | Authentication error |
+| 4 | Authorization error |
+| 5 | API error (4xx/5xx) |
+
+## Error Format
+
+```json
+{"error":true,"code":"AUTH_ERROR","message":"Not authenticated.","details":{"status_code":401}}
+```
+
+## Architecture
+
+The CLI uses a **generic `api` command + route registry** architecture:
+
+1. `cio api <path>` — a single command that takes any API path with `{placeholder}` params
+2. OpenAPI specs are downloaded from the live API on first use and cached locally under `~/.cio/cache/specs/` (24h TTL, ETag-based conditional refresh). Use `cio schema --refresh` to force re-download.
+3. `internal/routes/enrichment.json` — summaries, param descriptions, query params for routes not yet annotated in the OpenAPI spec
+
+```bash
+# Discover resources
+cio schema
+
+# List endpoints for a resource
+cio schema campaigns
+
+# Inspect a method's parameters
+cio schema campaigns.list
+
+# Make an API call
+cio api /v1/environments/{environment_id}/campaigns --params '{"environment_id": "123"}'
+
+# CDP Pipelines (workspace_id = environment_id)
+cio api /cdp/api/workspaces/{workspace_id}/sources --params '{"workspace_id": "123"}'
+cio schema sources
+```
+
+## Development
+
+```bash
+go build -o cio .
+go test ./...
+go test ./... -v -run TestAuthLogin
+```
+
+## License
+
+Licensed under Apache License 2.0 with the Commons Clause Restriction. See [LICENSE](LICENSE).

package/package.json

@@ -1,20 +1,85 @@
 {
   "name": "@customerio/cli",
-  "version": "0.0.0-bootstrap",
-  "description": "Bootstrap placeholder for Customer.io CLI trusted publishing setup",
-  "main": "index.js",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+  "version": "0.0.2",
+  "description": "Agent-first CLI for Customer.io APIs",
+  "bin": {
+    "cio": ".npm/run.js"
+  },
+  "files": [
+    ".npm/run.js",
+    "LICENSE",
+    "README.md"
+  ],
+  "optionalDependencies": {
+    "@customerio/cli-darwin-arm64": "0.0.2",
+    "@customerio/cli-darwin-x64": "0.0.2",
+    "@customerio/cli-linux-arm64": "0.0.2",
+    "@customerio/cli-linux-x64": "0.0.2",
+    "@customerio/cli-win32-arm64": "0.0.2",
+    "@customerio/cli-win32-x64": "0.0.2"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "customerioCli": {
+    "platforms": [
+      {
+        "goos": "darwin",
+        "goarch": "arm64",
+        "npm": "darwin-arm64",
+        "os": "darwin",
+        "cpu": "arm64",
+        "ext": ""
+      },
+      {
+        "goos": "darwin",
+        "goarch": "amd64",
+        "npm": "darwin-x64",
+        "os": "darwin",
+        "cpu": "x64",
+        "ext": ""
+      },
+      {
+        "goos": "linux",
+        "goarch": "arm64",
+        "npm": "linux-arm64",
+        "os": "linux",
+        "cpu": "arm64",
+        "ext": ""
+      },
+      {
+        "goos": "linux",
+        "goarch": "amd64",
+        "npm": "linux-x64",
+        "os": "linux",
+        "cpu": "x64",
+        "ext": ""
+      },
+      {
+        "goos": "windows",
+        "goarch": "arm64",
+        "npm": "win32-arm64",
+        "os": "win32",
+        "cpu": "arm64",
+        "ext": ".exe"
+      },
+      {
+        "goos": "windows",
+        "goarch": "amd64",
+        "npm": "win32-x64",
+        "os": "win32",
+        "cpu": "x64",
+        "ext": ".exe"
+      }
+    ]
   },
-  "keywords": [],
-  "author": "",
   "license": "SEE LICENSE IN LICENSE",
-  "type": "commonjs",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/customerio/cli.git"
   },
-  "publishConfig": {
-    "access": "public"
+  "engines": {
+    "node": ">=16"
   }
 }