@withone/cli 1.12.2

package/README.md

@@ -0,0 +1,380 @@
+# One CLI
+
+One CLI to connect AI agents to every API on the internet.
+
+One gives your AI agent authenticated access to 200+ platforms — Gmail, Slack, Shopify, HubSpot, Stripe, Notion, and everything else — through a single interface. No API keys to juggle, no OAuth flows to build, no request formats to memorize. Connect a platform once, and your agent can search for actions, read the docs, and execute API calls in seconds.
+
+## Install
+
+```bash
+npx @picahq/cli@latest init
+```
+
+Or install globally:
+
+```bash
+npm install -g @picahq/cli
+one init
+```
+
+`one init` walks you through setup: enter your [API key](https://app.withone.ai/settings/api-keys), pick your AI agents, and you're done. The MCP server gets installed automatically.
+
+Requires Node.js 18+.
+
+## Quick start
+
+```bash
+# Connect a platform
+one add gmail
+
+# See what you're connected to
+one list
+
+# Search for actions you can take
+one actions search gmail "send email" -t execute
+
+# Read the docs for an action
+one actions knowledge gmail <actionId>
+
+# Execute it
+one actions execute gmail <actionId> <connectionKey> \
+  -d '{"to": "jane@example.com", "subject": "Hello", "body": "Sent from my AI agent"}'
+```
+
+That's it. Five commands to go from zero to sending an email through Gmail's API — fully authenticated, correctly formatted, without touching a single OAuth token.
+
+### Multi-step flows
+
+Chain actions across platforms into reusable workflows:
+
+```bash
+# Create a flow that looks up a Stripe customer and sends a Gmail welcome email
+one flow create welcome-customer --definition '{
+  "key": "welcome-customer",
+  "name": "Welcome New Customer",
+  "version": "1",
+  "inputs": {
+    "stripeKey": { "type": "string", "required": true, "connection": { "platform": "stripe" } },
+    "gmailKey": { "type": "string", "required": true, "connection": { "platform": "gmail" } },
+    "email": { "type": "string", "required": true }
+  },
+  "steps": [
+    { "id": "find", "name": "Find customer", "type": "action",
+      "action": { "platform": "stripe", "actionId": "<actionId>", "connectionKey": "$.input.stripeKey",
+        "data": { "query": "email:'\''{{$.input.email}}'\''" } } },
+    { "id": "send", "name": "Send email", "type": "action",
+      "if": "$.steps.find.response.data.length > 0",
+      "action": { "platform": "gmail", "actionId": "<actionId>", "connectionKey": "$.input.gmailKey",
+        "data": { "to": "{{$.input.email}}", "subject": "Welcome!", "body": "Thanks for joining." } } }
+  ]
+}'
+
+# Validate it
+one flow validate welcome-customer
+
+# Run it — connection keys auto-resolve if you have one connection per platform
+one flow execute welcome-customer -i email=jane@example.com
+```
+
+Workflows are stored as JSON at `.one/flows/<key>.flow.json` and support conditions, loops, parallel steps, transforms, and more. Run `one guide flows` for the full reference.
+
+## How it works
+
+```
+Your AI Agent
+    ↓
+  One CLI
+    ↓
+  One API (api.withone.ai/v1/passthrough)
+    ↓
+  Gmail / Slack / Shopify / HubSpot / Stripe / ...
+```
+
+Every API call routes through One's passthrough proxy. One injects the right credentials, handles rate limiting, and normalizes responses. You never see or manage raw OAuth tokens — your connection key is all you need.
+
+## Commands
+
+### `one init`
+
+Set up your API key and install the MCP server into your AI agents.
+
+```bash
+one init
+```
+
+Supports Claude Code, Claude Desktop, Cursor, Windsurf, Codex, and Kiro. Installs globally by default, or per-project with `-p` so your team can share configs (each person uses their own API key).
+
+If you've already set up, `one init` shows your current status and lets you update your key, install to more agents, or reconfigure.
+
+| Flag | What it does |
+|------|-------------|
+| `-y` | Skip confirmations |
+| `-g` | Install globally (default) |
+| `-p` | Install for current project only |
+
+### `one add <platform>`
+
+Connect a new platform via OAuth.
+
+```bash
+one add shopify
+one add hub-spot
+one add gmail
+```
+
+Opens your browser, you authorize, done. The CLI polls until the connection is live. Platform names are kebab-case — run `one platforms` to see them all.
+
+### `one list`
+
+List your active connections with their status and connection keys.
+
+```bash
+one list
+```
+
+```
+  ● gmail       operational   live::gmail::default::abc123
+  ● slack       operational   live::slack::default::def456
+  ● shopify     operational   live::shopify::default::ghi789
+```
+
+You need the connection key (rightmost column) when executing actions.
+
+### `one platforms`
+
+Browse all 200+ available platforms.
+
+```bash
+one platforms              # all platforms
+one platforms -c "CRM"     # filter by category
+one platforms --json       # machine-readable output
+```
+
+### `one actions search <platform> <query>`
+
+Search for API actions on a connected platform using natural language.
+
+```bash
+one actions search shopify "list products"
+one actions search hub-spot "create contact" -t execute
+one actions search gmail "send email"
+```
+
+Returns the top 5 matching actions with their action IDs, HTTP methods, and paths. Use `-t execute` when you intend to run the action, or `-t knowledge` (default) when you want to learn about it or write code against it.
+
+### `one actions knowledge <platform> <actionId>`
+
+Get the full documentation for an action — parameters, validation rules, request/response structure, examples, and the exact API request format.
+
+```bash
+one actions knowledge shopify 67890abcdef
+```
+
+Always read the knowledge before executing. It tells you exactly what parameters are required, what format they need, and any platform-specific quirks.
+
+### `one actions execute <platform> <actionId> <connectionKey>`
+
+Execute an API action on a connected platform.
+
+```bash
+# Simple GET
+one actions execute shopify <actionId> <connectionKey>
+
+# POST with data
+one actions execute hub-spot <actionId> <connectionKey> \
+  -d '{"properties": {"email": "jane@example.com", "firstname": "Jane"}}'
+
+# With path variables
+one actions execute shopify <actionId> <connectionKey> \
+  --path-vars '{"order_id": "12345"}'
+
+# With query params
+one actions execute stripe <actionId> <connectionKey> \
+  --query-params '{"limit": "10"}'
+```
+
+| Option | What it does |
+|--------|-------------|
+| `-d, --data <json>` | Request body (POST, PUT, PATCH) |
+| `--path-vars <json>` | Replace `{variables}` in the URL path |
+| `--query-params <json>` | Query string parameters |
+| `--headers <json>` | Additional request headers |
+| `--form-data` | Send as multipart/form-data |
+| `--form-url-encoded` | Send as application/x-www-form-urlencoded |
+| `--dry-run` | Show the request without executing it |
+
+### `one guide [topic]`
+
+Get the full CLI usage guide, designed for AI agents that only have the binary (no MCP, no IDE skills).
+
+```bash
+one guide                 # full guide (all topics)
+one guide overview        # setup, --agent flag, discovery workflow
+one guide actions         # search, knowledge, execute workflow
+one guide flows           # multi-step API workflows
+
+one --agent guide         # full guide as structured JSON
+one --agent guide flows   # single topic as JSON
+```
+
+Topics: `overview`, `actions`, `flows`, `all` (default).
+
+In agent mode (`--agent`), the JSON response includes the guide content and an `availableTopics` array so agents can discover what sections exist.
+
+### `one flow create [key]`
+
+Create a workflow from a JSON definition. Workflows are saved to `.one/flows/<key>.flow.json`.
+
+```bash
+# From a --definition flag
+one flow create welcome-customer --definition '{"key":"welcome-customer","name":"Welcome","version":"1","inputs":{},"steps":[]}'
+
+# From stdin
+cat flow.json | one flow create
+
+# Custom output path
+one flow create my-flow --definition '...' -o ./custom/path.json
+```
+
+| Option | What it does |
+|--------|-------------|
+| `--definition <json>` | Workflow definition as a JSON string |
+| `-o, --output <path>` | Custom output path (default: `.one/flows/<key>.flow.json`) |
+
+### `one flow execute <key>`
+
+Execute a workflow by key or file path. Pass inputs with repeatable `-i` flags.
+
+```bash
+# Execute with inputs
+one flow execute welcome-customer \
+  -i customerEmail=jane@example.com
+
+# Dry run — validate and show plan without executing
+one flow execute welcome-customer --dry-run -i customerEmail=jane@example.com
+
+# Verbose — show each step as it runs
+one flow execute welcome-customer -v -i customerEmail=jane@example.com
+```
+
+Connection inputs with a `connection` field in the workflow definition are auto-resolved when the user has exactly one connection for that platform.
+
+Press Ctrl+C during execution to pause — the run can be resumed later with `one flow resume <runId>`.
+
+| Option | What it does |
+|--------|-------------|
+| `-i, --input <name=value>` | Input parameter (repeatable) |
+| `--dry-run` | Validate and show execution plan without running |
+| `-v, --verbose` | Show full request/response for each step |
+
+### `one flow list`
+
+List all workflows saved in `.one/flows/`.
+
+```bash
+one flow list
+```
+
+### `one flow validate <key>`
+
+Validate a workflow JSON file against the schema.
+
+```bash
+one flow validate welcome-customer
+```
+
+### `one flow resume <runId>`
+
+Resume a paused or failed workflow run from where it left off.
+
+```bash
+one flow resume abc123
+```
+
+### `one flow runs [flowKey]`
+
+List workflow runs, optionally filtered by workflow key.
+
+```bash
+one flow runs                    # all runs
+one flow runs welcome-customer   # runs for a specific workflow
+```
+
+### `one config`
+
+Configure access control for the MCP server. Optional — full access is the default.
+
+```bash
+one config
+```
+
+| Setting | Options | Default |
+|---------|---------|---------|
+| Permission level | `admin` / `write` / `read` | `admin` |
+| Connection scope | All or specific connections | All |
+| Action scope | All or specific action IDs | All |
+| Knowledge-only mode | Enable/disable execution | Off |
+
+Settings propagate automatically to all installed agent configs.
+
+## The workflow
+
+The power of One is in the workflow. Every interaction follows the same pattern:
+
+```
+one list                    → What am I connected to?
+one actions search          → What can I do?
+one actions knowledge       → How do I do it?
+one actions execute         → Do it.
+```
+
+This is the same workflow whether you're sending emails, creating CRM contacts, processing payments, managing inventory, or posting to Slack. One pattern, any platform.
+
+For multi-step workflows that chain actions across platforms:
+
+```
+one actions knowledge       → Learn each action's schema
+one flow create             → Define the workflow as JSON
+one flow validate           → Check it
+one flow execute            → Run it
+```
+
+Workflows support conditions, loops, parallel execution, transforms, code steps, and file I/O. Run `one guide flows` for the full schema reference and examples.
+
+## For AI agents
+
+If you're an AI agent with only the `one` binary (no MCP server or IDE skills), start with `one --agent guide` to get the full usage guide as structured JSON. This teaches you the complete workflow, JSON schemas, selector syntax, and more — everything you need to bootstrap yourself.
+
+If you're an AI agent using the One MCP server, the tools map directly:
+
+| MCP Tool | CLI Command |
+|----------|------------|
+| `list_one_integrations` | `one list` + `one platforms` |
+| `search_one_platform_actions` | `one actions search` |
+| `get_one_action_knowledge` | `one actions knowledge` |
+| `execute_one_action` | `one actions execute` |
+
+The workflow is the same: list → search → knowledge → execute. Never skip the knowledge step — it contains required parameter info and platform-specific details that are critical for building correct requests.
+
+## MCP server installation
+
+`one init` handles this automatically. Here's where configs go:
+
+| Agent | Global | Project |
+|-------|--------|---------|
+| Claude Code | `~/.claude.json` | `.mcp.json` |
+| Claude Desktop | Platform-specific app support dir | — |
+| Cursor | `~/.cursor/mcp.json` | `.cursor/mcp.json` |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` | — |
+| Codex | `~/.codex/config.toml` | `.codex/config.toml` |
+| Kiro | `~/.kiro/settings/mcp.json` | `.kiro/settings/mcp.json` |
+
+Project configs can be committed to your repo. Each team member runs `one init` with their own API key.
+
+## Development
+
+```bash
+npm run dev        # watch mode
+npm run build      # production build
+npm run typecheck  # type check
+```

package/bin/cli.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+import '../dist/index.js';

package/dist/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node