@withone/cli 1.28.0 → 1.31.0

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@withone/cli",
-  "version": "1.28.0",
+  "version": "1.31.0",
   "description": "CLI for managing One",
   "type": "module",
   "files": [
     "bin",
     "dist",
-    "skills"
+    "skills",
+    "profiles"
   ],
   "bin": {
     "one": "./bin/cli.js"
@@ -24,7 +25,11 @@
     "picocolors": "^1.1.1",
     "smol-toml": "^1.6.0"
   },
+  "optionalDependencies": {
+    "better-sqlite3": "^11.7.0"
+  },
   "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^22.13.1",
     "tsup": "^8.3.6",
     "typescript": "^5.7.3"
@@ -36,4 +41,4 @@
   "engines": {
     "node": ">=18"
   }
-}
+}

package/profiles/attio/attioCompanies.json

@@ -0,0 +1,16 @@
+{
+  "description": "Attio companies — CRM company records with domains, industry, and custom attributes",
+  "platform": "attio",
+  "model": "attioCompanies",
+  "connectionKey": "AUTO",
+  "actionId": "conn_mod_def::GJt0lFZ6kpk::attio-companies-list",
+  "resultsPath": "companies",
+  "idField": "id",
+  "pagination": {
+    "type": "offset",
+    "passAs": "body:offset"
+  },
+  "limitLocation": "body",
+  "limitParam": "limit",
+  "defaultLimit": 100
+}

package/profiles/attio/attioPeople.json

@@ -0,0 +1,17 @@
+{
+  "description": "Attio people — CRM contact records with emails, phone numbers, and custom attributes",
+  "platform": "attio",
+  "model": "attioPeople",
+  "connectionKey": "AUTO",
+  "identityKey": "primary_email_address",
+  "actionId": "conn_mod_def::GJt0lFZ6kpk::attio-people-list",
+  "resultsPath": "people",
+  "idField": "id",
+  "pagination": {
+    "type": "offset",
+    "passAs": "body:offset"
+  },
+  "limitLocation": "body",
+  "limitParam": "limit",
+  "defaultLimit": 100
+}

package/profiles/fathom/meetings.json

@@ -0,0 +1,27 @@
+{
+  "description": "Fathom meetings — recorded meetings with transcripts, summaries, action items, and attendees",
+  "platform": "fathom",
+  "model": "meetings",
+  "connectionKey": "AUTO",
+  "actionId": "conn_mod_def::fathom::meetings-list",
+  "resultsPath": "items",
+  "idField": "recording_id",
+  "pagination": {
+    "type": "cursor",
+    "nextPath": "next_cursor",
+    "passAs": "query:cursor",
+    "hasMorePath": "has_more"
+  },
+  "dateFilter": { "param": "created_after", "format": "iso8601" },
+  "defaultLimit": 50,
+  "queryParams": {
+    "include_action_items": "true"
+  },
+  "enrich": {
+    "actionId": "conn_mod_def::GIpBYFV5Mog::G6aag6ykQ-uD6XCeUUnq7Q",
+    "pathVars": {
+      "RECORDING_ID": "{recording_id}"
+    },
+    "concurrency": 3
+  }
+}

package/profiles/gmail/gmailThreads.json

@@ -0,0 +1,28 @@
+{
+  "description": "Gmail email threads — primary inbox with full message bodies (no attachments)",
+  "platform": "gmail",
+  "model": "gmailThreads",
+  "connectionKey": "AUTO",
+  "actionId": "conn_mod_def::GJ3ok-Q0D40::oLWNlcx4QDORaL_18z-MsQ",
+  "resultsPath": "threads",
+  "idField": "id",
+  "pagination": {
+    "type": "token",
+    "nextPath": "nextPageToken",
+    "passAs": "query:pageToken"
+  },
+  "limitParam": "maxResults",
+  "defaultLimit": 100,
+  "pathVars": { "userId": "me" },
+  "queryParams": { "q": "category:primary" },
+  "enrich": {
+    "actionId": "conn_mod_def::GJ3ok0Eq0R8::AAzgZVLqTg2iBuITKpJLZg",
+    "pathVars": { "userId": "me", "id": "{id}" },
+    "queryParams": { "format": "full" },
+    "exclude": [
+      "messages[].payload.parts[].body.data",
+      "messages[].payload.body.data"
+    ],
+    "concurrency": 5
+  }
+}

package/profiles/google-calendar/events.json

@@ -0,0 +1,17 @@
+{
+  "description": "Google Calendar events — meetings, appointments, and all-day events with attendees and location",
+  "platform": "google-calendar",
+  "model": "events",
+  "connectionKey": "AUTO",
+  "actionId": "conn_mod_def::GJ5x5pOh2TU::gcal-events-list",
+  "resultsPath": "items",
+  "idField": "id",
+  "pagination": {
+    "type": "token",
+    "nextPath": "nextPageToken",
+    "passAs": "query:pageToken"
+  },
+  "pathVars": { "calendarId": "primary" },
+  "defaultLimit": 250,
+  "limitParam": "maxResults"
+}

package/profiles/notion/search.json

@@ -0,0 +1,18 @@
+{
+  "description": "Notion pages and databases — full workspace search with titles, properties, and metadata",
+  "platform": "notion",
+  "model": "search",
+  "connectionKey": "AUTO",
+  "actionId": "conn_mod_def::GJ5En67fz04::-CJAS419SVWm7L2l6brp6A",
+  "resultsPath": "results",
+  "idField": "id",
+  "pagination": {
+    "type": "cursor",
+    "nextPath": "next_cursor",
+    "passAs": "body:start_cursor",
+    "hasMorePath": "has_more"
+  },
+  "limitLocation": "body",
+  "limitParam": "page_size",
+  "defaultLimit": 100
+}

package/profiles/stripe/balanceTransactions.json

@@ -0,0 +1,17 @@
+{
+  "description": "Stripe balance transactions — payments, refunds, payouts, and fees with amount, currency, and status",
+  "platform": "stripe",
+  "model": "balanceTransactions",
+  "connectionKey": "AUTO",
+  "actionId": "conn_mod_def::GGx6clhYjSQ::3kEaM3HQTA2JRfW3DzXC4g",
+  "resultsPath": "data",
+  "idField": "id",
+  "pagination": {
+    "type": "id",
+    "passAs": "query:starting_after",
+    "hasMorePath": "has_more",
+    "idField": "id"
+  },
+  "defaultLimit": 100,
+  "limitParam": "limit"
+}

package/profiles/stripe/customers.json

@@ -0,0 +1,18 @@
+{
+  "description": "Stripe customers — customer records with email, name, payment methods, and subscription status",
+  "platform": "stripe",
+  "model": "customers",
+  "connectionKey": "AUTO",
+  "actionId": "conn_mod_def::GGx6clhYjSQ::customers-list",
+  "resultsPath": "data",
+  "idField": "id",
+  "identityKey": "email",
+  "pagination": {
+    "type": "id",
+    "passAs": "query:starting_after",
+    "hasMorePath": "has_more",
+    "idField": "id"
+  },
+  "defaultLimit": 100,
+  "limitParam": "limit"
+}

package/skills/one/SKILL.md

@@ -22,6 +22,8 @@ description: |
 
 You have access to the One CLI which lets you interact with 250+ third-party platforms through their APIs. Always include the `--agent` flag right after `one` for structured JSON output.
 
+If the user wants a separate API key / connections for a specific project (vs. their default), walk them through running `one init` from that project folder and picking the "project" scope — see `references/scoping.md`.
+
 ## Core Workflow: search -> knowledge -> execute
 
 Always follow this sequence when the user wants to do something on a connected platform:
@@ -74,6 +76,10 @@ Options:
 - `--form-data` — Send as multipart/form-data
 - `--form-url-encoded` — Send as application/x-www-form-urlencoded
 - `--dry-run` — Preview the request without executing
+- `--mock` — Return example response without making an API call (useful for building UI)
+- `--skip-validation` — Skip input validation against the action schema
+
+The CLI validates required parameters before executing. Missing params return a structured error with the flag name, parameter name, and description. Pass `--skip-validation` to bypass.
 
 Examples:
 ```bash
@@ -95,6 +101,18 @@ one --agent actions execute gmail <actionId> <connectionKey> \
   --query-params '{"format": "metadata", "metadataHeaders": ["From", "Subject", "Date"]}'
 ```
 
+### Parallel execution
+
+Execute multiple actions concurrently with `--parallel`, separating each action with `--`:
+
+```bash
+one --agent actions execute --parallel \
+  gmail send-email conn123 -d '{"to":"a@b.com"}' \
+  -- slack post-message conn456 -d '{"text":"done"}'
+```
+
+All segments are validated before any execution. Failed actions don't block others. Use `--max-concurrency <n>` (default 5) to control batching. Agent-mode output: `{"parallel":true,"results":[...],"succeeded":N,"failed":N,"totalDurationMs":N}`.
+
 ## Error Handling
 
 All errors return JSON: `{"error": "message"}`. Parse output as JSON and check for the `error` key.
@@ -120,6 +138,33 @@ Knowledge and search responses are cached locally (`~/.one/cache/`). Subsequent
 - Manage cache: `one cache list`, `one cache clear`, `one cache update-all`
 - `actions execute` is NEVER cached — always fresh
 
+## Local Data Sync
+
+Sync platform data into local SQLite for instant queries, full-text search, scheduled refresh, and change-driven automation.
+
+```bash
+# First time only
+one sync install
+
+# Check built-in profiles (pre-validated configs for common platforms)
+one --agent sync profiles
+
+# Setup (uses built-in if available, otherwise auto-infers + auto-tests)
+one --agent sync init stripe balanceTransactions
+# If _complete: true and _test.ok: true → go straight to sync run
+
+# Sync + query
+one --agent sync run stripe
+one --agent sync query stripe/balanceTransactions --where "status=available" --limit 20
+one --agent sync search "refund"                 # FTS across all synced platforms
+one --agent sync list stripe                     # progress + freshness
+
+# Schedule unattended syncs
+one sync schedule add stripe --every 1h
+```
+
+**Advanced features** (enrich, transform, exclude, identityKey, hooks, --full-refresh, --where-sql delete, cursor resume): run `one guide sync` for the full reference.
+
 ## Beyond Single Actions
 
 One also supports more advanced patterns. Read the relevant reference file before using these:

package/skills/one/references/flows.md

@@ -628,6 +628,7 @@ one --agent flow validate <key>
 one --agent flow execute <key> -i key=value
 one --agent flow execute <key> --dry-run -i key=value
 one --agent flow execute <key> --dry-run --mock -i key=value
+one --agent flow execute <key> --skip-validation -i key=value
 one --agent flow execute <key> --allow-bash -i key=value
 one --agent flow runs [flowKey]
 one --agent flow resume <runId>
@@ -635,9 +636,12 @@ one --agent flow resume <runId>
 
 ## Important Notes
 
+- **Prefer passthrough actions over custom actions.** Custom actions add server-side fan-out that causes timeouts at scale. The flow runner handles pagination, retries, and rate limiting locally. Search with `-t knowledge` to find passthrough endpoints (e.g. GET `/gmail/v1/users/{userId}/threads` instead of POST `/gmail/get-threads`)
 - Connection keys are inputs, not hardcoded — makes workflows portable
 - Action IDs in examples are placeholders — always use `actions search` to find real IDs
 - Code steps support `require('crypto')`, `require('buffer')`, `require('url')`, `require('path')` — `fs`, `http`, `child_process` are blocked
 - Bash steps require `--allow-bash` flag
+- Action steps validate required params before executing — pass `--skip-validation` to bypass
+- `--mock` now returns realistic example data from action schemas (instead of echoed config)
 - State is persisted after every step — resume picks up where it left off
 - For bash+Claude steps, always set timeout to 180000+ and run sequentially (not in parallel)

package/skills/one/references/scoping.md

@@ -0,0 +1,35 @@
+# Project vs. global config
+
+The One CLI can be configured at two scopes:
+
+- **Global** — `~/.one/config.json`. Applies everywhere the user runs `one`.
+- **Project** — `~/.one/projects/<slug>/config.json`, where `<slug>` is the project root path with slashes replaced by dashes (e.g. `/Users/jane/acme` → `-Users-jane-acme`). Only applies when running `one` from inside that project folder.
+
+**Resolution order:** env vars → `.onerc` in cwd → project config → global config. Project config wins when present; otherwise the CLI falls back to the global config.
+
+## When to suggest project scope
+
+Suggest project scope when the user wants any of the following for a specific folder only, without changing their default setup:
+
+- A different One API key (e.g. sandbox workspace for a client project)
+- A different set of connections / connection keys
+- Different access control (permissions, scoped connections, knowledge-only mode)
+
+## How to set it up
+
+Do **not** hand-edit `.onerc` or config files. Walk the user through the interactive init:
+
+```bash
+cd /path/to/the/project
+one init
+```
+
+When `init` asks "Where should this setup live?", pick **"This project only"**. Init will write the config to `~/.one/projects/<slug>/config.json` and everything else (skill install, MCP) stays untouched.
+
+To see which config is currently active and the full fallback chain:
+
+```bash
+one --agent config path
+```
+
+To switch an existing project back to using the global config, delete its project config file — the CLI will automatically fall back to global on the next run.