Big News: Socket raises $60M Series C at a $1B valuation to secure software supply chains for AI-driven development.Announcement →
Sign In

@withone/cli

Package Overview
Dependencies
Maintainers
1
Versions
60
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

@withone/cli - npm Package Compare versions

Comparing version
1.12.2
 to
1.12.3
+151
skills/one-actions/SKILL.md
---
name: one-actions
description: |
Use the One CLI to interact with 200+ third-party platforms (Gmail, Slack, HubSpot, Shopify, etc.) through their APIs. This skill handles the full workflow: listing connections, searching for available actions, reading action documentation, and executing API calls against connected platforms.
TRIGGER when the user wants to:
- List their connected platforms or connections (e.g., "what platforms am I connected to", "show my connections")
- Search for what they can do on a platform (e.g., "what can I do with Gmail", "find Shopify actions for creating products", "search HubSpot for contacts")
- Understand how an API action works before using it (e.g., "how do I send an email with Gmail", "show me the docs for this action")
- Execute an action on a connected platform (e.g., "send an email via Gmail", "create a contact in HubSpot", "list my Shopify orders", "fetch my calendar events")
- Anything involving third-party platform integrations, API calls to external services through One, or using connected apps
DO NOT TRIGGER for:
- Setting up One or installing MCP (that's `one init`)
- Configuring access control (that's `one config`)
- Adding new connections (that's `one connection add`)
---
# One Actions CLI Workflow
You have access to the One CLI which lets you interact with 200+ third-party platforms through their APIs. The CLI handles authentication, request building, and execution through One's passthrough proxy.
## The Workflow
Always follow this sequence — each step builds on the previous one:
1. **List connections** to see what platforms the user has connected
2. **Search actions** to find the right API action for what the user wants to do
3. **Get knowledge** to understand the action's parameters, requirements, and structure
4. **Execute** the action with the correct parameters
Never skip the knowledge step before executing — it contains critical information about required parameters, validation rules, and request structure that you need to build a correct request.
## Commands
### 1. List Connections
```bash
one --agent connection list
```
Returns JSON with all connected platforms, their status, and connection keys. You need the **connection key** for executing actions, and the **platform name** (kebab-case) for searching actions.
Output format:
```json
{"connections": [{"platform": "gmail", "state": "active", "key": "conn_abc123"}, ...]}
```
### 2. Search Actions
```bash
one --agent actions search <platform> <query>
```
Search for actions on a specific platform using natural language. Returns JSON with up to 5 matching actions including their action IDs, HTTP methods, and paths.
- `<platform>` — Platform name in kebab-case exactly as shown in the connections list (e.g., `gmail`, `shopify`, `hub-spot`)
- `<query>` — Natural language description of what you want to do (e.g., `"send email"`, `"list contacts"`, `"create order"`)
Options:
- `-t, --type <execute|knowledge>` — Use `execute` when the user wants to perform an action, `knowledge` when they want documentation or want to write code. Defaults to `knowledge`.
Example:
```bash
one --agent actions search gmail "send email" -t execute
```
Output format:
```json
{"actions": [{"_id": "abc123", "title": "Send Email", "tags": [...], "method": "POST", "path": "/messages/send"}, ...]}
```
### 3. Get Action Knowledge
```bash
one --agent actions knowledge <platform> <actionId>
```
Get comprehensive documentation for an action including parameters, requirements, validation rules, request/response structure, and examples. Returns JSON with the full API knowledge and HTTP method.
Always call this before executing — it tells you exactly what parameters are required and how to structure the request.
Example:
```bash
one --agent actions knowledge gmail 67890abcdef
```
Output format:
```json
{"knowledge": "...full API documentation and guidance...", "method": "POST"}
```
### 4. Execute Action
```bash
one --agent actions execute <platform> <actionId> <connectionKey> [options]
```
Execute an action on a connected platform. Returns JSON with the request details and response data. You must have retrieved the knowledge for this action first.
- `<platform>` — Platform name in kebab-case
- `<actionId>` — Action ID from the search results
- `<connectionKey>` — Connection key from `one connection list`
Options:
- `-d, --data <json>` — Request body as JSON string (for POST, PUT, PATCH)
- `--path-vars <json>` — Path variables as JSON (for URLs with `{id}` placeholders)
- `--query-params <json>` — Query parameters as JSON
- `--headers <json>` — Additional headers as JSON
- `--form-data` — Send as multipart/form-data instead of JSON
- `--form-url-encoded` — Send as application/x-www-form-urlencoded
- `--dry-run` — Show the request that would be sent without executing it
Examples:
```bash
# Simple GET request
one --agent actions execute shopify <actionId> <connectionKey>
# POST with data
one --agent actions execute hub-spot <actionId> <connectionKey> \
-d '{"properties": {"email": "jane@example.com", "firstname": "Jane"}}'
# With path variables and query params
one --agent actions execute shopify <actionId> <connectionKey> \
--path-vars '{"order_id": "12345"}' \
--query-params '{"limit": "10"}'
```
Output format:
```json
{"request": {"method": "POST", "url": "https://..."}, "response": {...}}
```
## Error Handling
All errors return JSON in agent mode:
```json
{"error": "Error message here"}
```
Parse the output as JSON. If the `error` key is present, the command failed — report the error message to the user.
## Important Notes
- **Always use `--agent` flag** — it produces structured JSON output without spinners, colors, or interactive prompts
- Platform names are always **kebab-case** (e.g., `hub-spot` not `HubSpot`, `ship-station` not `ShipStation`)
- Always use the **exact action ID** from search results — don't guess or construct them
- Always read the knowledge output carefully — it tells you which parameters are required vs optional, what format they need to be in, and any caveats specific to that API
- JSON values passed to `-d`, `--path-vars`, `--query-params`, and `--headers` must be valid JSON strings (use single quotes around the JSON to avoid shell escaping issues)
- If search returns no results, try broader queries (e.g., `"list"` instead of `"list active premium customers"`)
- The execute command respects access control settings configured via `one config` — if execution is blocked, the user may need to adjust their permissions
+603
skills/one-flow/SKILL.md
---
name: one-flow
description: |
Build and execute multi-step API workflows that chain actions across platforms — like n8n/Zapier but file-based. Workflows are JSON files stored at `.one/flows/<key>.flow.json`.
TRIGGER when the user wants to:
- Create a multi-step workflow or automation (e.g., "create a workflow that looks up a customer in Stripe and sends them an email")
- Chain multiple API actions together across platforms
- Build a pipeline or sequence of API calls
- Execute, validate, or manage existing workflows
- Automate a process involving multiple connected platforms
- Schedule or orchestrate a series of actions
DO NOT TRIGGER for:
- Single action execution (use one-actions skill instead)
- Setting up One or installing MCP (that's `one init`)
- Adding new connections (that's `one connection add`)
---
# One Workflows — Multi-Step API Workflows
You have access to the One CLI's workflow engine, which lets you create and execute multi-step API workflows as JSON files. Workflows chain actions across platforms — e.g., look up a Stripe customer, then send them a welcome email via Gmail.
## 1. Overview
- Workflows are JSON files stored at `.one/flows/<key>.flow.json`
- All dynamic values (including connection keys) are declared as **inputs**
- Each workflow has a unique **key** used to reference and execute it
- Executed via `one --agent flow execute <key> -i name=value`
## 2. Building a Workflow — Step-by-Step Process
**You MUST follow this process to build a correct workflow:**
### Step 1: Discover connections
```bash
one --agent connection list
```
Find out which platforms are connected and get their connection keys.
### Step 2: For EACH API action needed, get the knowledge
```bash
# Find the action ID
one --agent actions search <platform> "<query>" -t execute
# Read the full docs — REQUIRED before adding to a workflow
one --agent actions knowledge <platform> <actionId>
```
**CRITICAL:** You MUST call `one actions knowledge` for every action you include in the workflow. The knowledge output tells you the exact request body structure, required fields, path variables, and query parameters. Without this, your workflow JSON will have incorrect data shapes.
### Step 3: Construct the workflow JSON
Using the knowledge gathered, build the workflow JSON with:
- All inputs declared (connection keys + user parameters)
- Each step with the correct actionId, platform, and data structure (from knowledge)
- Data wired between steps using `$.input.*` and `$.steps.*` selectors
### Step 4: Write the workflow file
```bash
one --agent flow create <key> --definition '<json>'
```
Or write directly to `.one/flows/<key>.flow.json`.
### Step 5: Validate
```bash
one --agent flow validate <key>
```
### Step 6: Execute
```bash
one --agent flow execute <key> -i connectionKey=xxx -i param=value
```
## 3. Workflow JSON Schema Reference
```json
{
"key": "welcome-customer",
"name": "Welcome New Customer",
"description": "Look up a Stripe customer and send them a welcome email via Gmail",
"version": "1",
"inputs": {
"stripeConnectionKey": {
"type": "string",
"required": true,
"description": "Stripe connection key from one connection list",
"connection": { "platform": "stripe" }
},
"gmailConnectionKey": {
"type": "string",
"required": true,
"description": "Gmail connection key from one connection list",
"connection": { "platform": "gmail" }
},
"customerEmail": {
"type": "string",
"required": true,
"description": "Customer email to look up"
}
},
"steps": [
{
"id": "stepId",
"name": "Human-readable label",
"type": "action",
"action": {
"platform": "stripe",
"actionId": "the-action-id-from-search",
"connectionKey": "$.input.stripeConnectionKey",
"data": {},
"pathVars": {},
"queryParams": {},
"headers": {}
}
}
]
}
```
### Input declarations
| Field | Type | Description |
|---|---|---|
| `type` | string | `string`, `number`, `boolean`, `object`, `array` |
| `required` | boolean | Whether this input must be provided (default: true) |
| `default` | any | Default value if not provided |
| `description` | string | Human-readable description |
| `connection` | object | Connection metadata: `{ "platform": "gmail" }` — enables auto-resolution |
**Connection inputs** have a `connection` field. If the user has exactly one connection for that platform, the workflow engine auto-resolves it.
## 4. Selector Syntax Reference
| Pattern | Resolves To |
|---|---|
| `$.input.gmailConnectionKey` | Input value (including connection keys) |
| `$.input.customerEmail` | Any input parameter |
| `$.steps.stepId.response` | Full API response from a step |
| `$.steps.stepId.response.data[0].email` | Nested field with array index |
| `$.steps.stepId.response.data[*].id` | Wildcard — maps array to field |
| `$.env.MY_VAR` | Environment variable |
| `$.loop.item` | Current loop item |
| `$.loop.i` | Current loop index |
| `"Hello {{$.steps.getUser.response.data.name}}"` | String interpolation |
**Rules:**
- A value that is purely `$.xxx` resolves to the raw type (object, array, number)
- A string containing `{{$.xxx}}` does string interpolation (stringifies objects)
- Selectors inside objects/arrays are resolved recursively
## 5. Step Types Reference
### `action` — Execute a One API action
```json
{
"id": "findCustomer",
"name": "Search Stripe customers",
"type": "action",
"action": {
"platform": "stripe",
"actionId": "conn_mod_def::xxx::yyy",
"connectionKey": "$.input.stripeConnectionKey",
"data": {
"query": "email:'{{$.input.customerEmail}}'"
}
}
}
```
### `transform` — Transform data with a JS expression
```json
{
"id": "extractNames",
"name": "Extract customer names",
"type": "transform",
"transform": {
"expression": "$.steps.findCustomer.response.data.map(c => c.name)"
}
}
```
The expression is evaluated with the full flow context as `$`.
### `code` — Run multi-line JavaScript
Unlike `transform` (single expression, implicit return), `code` runs a full function body with explicit `return`. Use it when you need variables, loops, try/catch, or `await`.
```json
{
"id": "processData",
"name": "Process and enrich data",
"type": "code",
"code": {
"source": "const customers = $.steps.listCustomers.response.data;\nconst enriched = customers.map(c => ({\n ...c,\n tier: c.spend > 1000 ? 'gold' : 'silver'\n}));\nreturn enriched;"
}
}
```
The `source` field contains a JS function body. The flow context is available as `$`. The function is async, so you can use `await`. The return value is stored as the step result.
### `condition` — If/then/else branching
```json
{
"id": "checkFound",
"name": "Check if customer was found",
"type": "condition",
"condition": {
"expression": "$.steps.findCustomer.response.data.length > 0",
"then": [
{ "id": "sendEmail", "name": "Send welcome email", "type": "action", "action": { "..." : "..." } }
],
"else": [
{ "id": "logNotFound", "name": "Log not found", "type": "transform", "transform": { "expression": "'Customer not found'" } }
]
}
}
```
### `loop` — Iterate over an array
```json
{
"id": "processOrders",
"name": "Process each order",
"type": "loop",
"loop": {
"over": "$.steps.listOrders.response.data",
"as": "order",
"indexAs": "i",
"maxIterations": 1000,
"maxConcurrency": 5,
"steps": [
{
"id": "createInvoice",
"name": "Create invoice for order",
"type": "action",
"action": {
"platform": "quickbooks",
"actionId": "...",
"connectionKey": "$.input.qbConnectionKey",
"data": { "amount": "$.loop.order.total" }
}
}
]
}
}
```
- `maxConcurrency` (optional): When set > 1, loop iterations run in parallel batches of that size. Default is sequential (1).
### `parallel` — Run steps concurrently
```json
{
"id": "parallelLookups",
"name": "Look up in parallel",
"type": "parallel",
"parallel": {
"maxConcurrency": 5,
"steps": [
{ "id": "getStripe", "name": "Get Stripe data", "type": "action", "action": { "...": "..." } },
{ "id": "getHubspot", "name": "Get HubSpot data", "type": "action", "action": { "...": "..." } }
]
}
}
```
### `file-read` — Read from filesystem
```json
{
"id": "readConfig",
"name": "Read config file",
"type": "file-read",
"fileRead": { "path": "./data/config.json", "parseJson": true }
}
```
### `file-write` — Write to filesystem
```json
{
"id": "writeResults",
"name": "Save results",
"type": "file-write",
"fileWrite": {
"path": "./output/results.json",
"content": "$.steps.transform.output",
"append": false
}
}
```
## 6. Error Handling
### `onError` strategies
```json
{
"id": "riskyStep",
"name": "Might fail",
"type": "action",
"onError": {
"strategy": "retry",
"retries": 3,
"retryDelayMs": 1000
},
"action": { "...": "..." }
}
```
| Strategy | Behavior |
|---|---|
| `fail` | Stop the flow immediately (default) |
| `continue` | Mark step as failed, continue to next step |
| `retry` | Retry up to N times with delay |
| `fallback` | On failure, execute a different step |
### Conditional execution
Skip a step based on previous results:
```json
{
"id": "sendEmail",
"name": "Send email only if customer found",
"type": "action",
"if": "$.steps.findCustomer.response.data.length > 0",
"action": { "...": "..." }
}
```
## 7. Updating Existing Workflows
To modify an existing workflow:
1. Read the workflow JSON file at `.one/flows/<key>.flow.json`
2. Understand its current structure
3. Use `one --agent actions knowledge <platform> <actionId>` for any new actions
4. Modify the JSON (add/remove/update steps, change data mappings, add inputs)
5. Write back the updated workflow file
6. Validate: `one --agent flow validate <key>`
## 8. Complete Examples
### Example 1: Simple 2-step — Search Stripe customer, send Gmail email
```json
{
"key": "welcome-customer",
"name": "Welcome New Customer",
"description": "Look up a Stripe customer and send them a welcome email",
"version": "1",
"inputs": {
"stripeConnectionKey": {
"type": "string",
"required": true,
"description": "Stripe connection key",
"connection": { "platform": "stripe" }
},
"gmailConnectionKey": {
"type": "string",
"required": true,
"description": "Gmail connection key",
"connection": { "platform": "gmail" }
},
"customerEmail": {
"type": "string",
"required": true,
"description": "Customer email to look up"
}
},
"steps": [
{
"id": "findCustomer",
"name": "Search for customer in Stripe",
"type": "action",
"action": {
"platform": "stripe",
"actionId": "STRIPE_SEARCH_CUSTOMERS_ACTION_ID",
"connectionKey": "$.input.stripeConnectionKey",
"data": {
"query": "email:'{{$.input.customerEmail}}'"
}
}
},
{
"id": "sendWelcome",
"name": "Send welcome email via Gmail",
"type": "action",
"if": "$.steps.findCustomer.response.data && $.steps.findCustomer.response.data.length > 0",
"action": {
"platform": "gmail",
"actionId": "GMAIL_SEND_EMAIL_ACTION_ID",
"connectionKey": "$.input.gmailConnectionKey",
"data": {
"to": "{{$.input.customerEmail}}",
"subject": "Welcome, {{$.steps.findCustomer.response.data[0].name}}!",
"body": "Thank you for being a customer. We're glad to have you!"
}
}
}
]
}
```
### Example 2: Conditional — Check if HubSpot contact exists, create or update
```json
{
"key": "sync-hubspot-contact",
"name": "Sync Contact to HubSpot",
"description": "Check if a contact exists in HubSpot, create if new or update if existing",
"version": "1",
"inputs": {
"hubspotConnectionKey": {
"type": "string",
"required": true,
"connection": { "platform": "hub-spot" }
},
"email": { "type": "string", "required": true },
"firstName": { "type": "string", "required": true },
"lastName": { "type": "string", "required": true }
},
"steps": [
{
"id": "searchContact",
"name": "Search for existing contact",
"type": "action",
"action": {
"platform": "hub-spot",
"actionId": "HUBSPOT_SEARCH_CONTACTS_ACTION_ID",
"connectionKey": "$.input.hubspotConnectionKey",
"data": {
"filterGroups": [{ "filters": [{ "propertyName": "email", "operator": "EQ", "value": "$.input.email" }] }]
}
}
},
{
"id": "createOrUpdate",
"name": "Create or update contact",
"type": "condition",
"condition": {
"expression": "$.steps.searchContact.response.total > 0",
"then": [
{
"id": "updateContact",
"name": "Update existing contact",
"type": "action",
"action": {
"platform": "hub-spot",
"actionId": "HUBSPOT_UPDATE_CONTACT_ACTION_ID",
"connectionKey": "$.input.hubspotConnectionKey",
"pathVars": { "contactId": "$.steps.searchContact.response.results[0].id" },
"data": {
"properties": { "firstname": "$.input.firstName", "lastname": "$.input.lastName" }
}
}
}
],
"else": [
{
"id": "createContact",
"name": "Create new contact",
"type": "action",
"action": {
"platform": "hub-spot",
"actionId": "HUBSPOT_CREATE_CONTACT_ACTION_ID",
"connectionKey": "$.input.hubspotConnectionKey",
"data": {
"properties": { "email": "$.input.email", "firstname": "$.input.firstName", "lastname": "$.input.lastName" }
}
}
}
]
}
}
]
}
```
### Example 3: Loop — Iterate over Shopify orders, create invoices
```json
{
"key": "shopify-to-invoices",
"name": "Shopify Orders to Invoices",
"description": "Fetch recent Shopify orders and create an invoice for each",
"version": "1",
"inputs": {
"shopifyConnectionKey": {
"type": "string",
"required": true,
"connection": { "platform": "shopify" }
},
"qbConnectionKey": {
"type": "string",
"required": true,
"connection": { "platform": "quick-books" }
}
},
"steps": [
{
"id": "listOrders",
"name": "List recent Shopify orders",
"type": "action",
"action": {
"platform": "shopify",
"actionId": "SHOPIFY_LIST_ORDERS_ACTION_ID",
"connectionKey": "$.input.shopifyConnectionKey",
"queryParams": { "status": "any", "limit": "50" }
}
},
{
"id": "createInvoices",
"name": "Create invoice for each order",
"type": "loop",
"loop": {
"over": "$.steps.listOrders.response.orders",
"as": "order",
"indexAs": "i",
"steps": [
{
"id": "createInvoice",
"name": "Create QuickBooks invoice",
"type": "action",
"onError": { "strategy": "continue" },
"action": {
"platform": "quick-books",
"actionId": "QB_CREATE_INVOICE_ACTION_ID",
"connectionKey": "$.input.qbConnectionKey",
"data": {
"Line": [
{
"Amount": "$.loop.order.total_price",
"Description": "Shopify Order #{{$.loop.order.order_number}}"
}
]
}
}
}
]
}
},
{
"id": "summary",
"name": "Generate summary",
"type": "transform",
"transform": {
"expression": "({ totalOrders: $.steps.listOrders.response.orders.length, processed: $.steps.createInvoices.output.length })"
}
}
]
}
```
## CLI Commands Reference
```bash
# Create a workflow
one --agent flow create <key> --definition '<json>'
# List all workflows
one --agent flow list
# Validate a workflow
one --agent flow validate <key>
# Execute a workflow
one --agent flow execute <key> -i connectionKey=value -i param=value
# Execute with dry run (validate only)
one --agent flow execute <key> --dry-run -i connectionKey=value
# Execute with verbose output
one --agent flow execute <key> -v -i connectionKey=value
# List workflow runs
one --agent flow runs [flowKey]
# Resume a paused/failed run
one --agent flow resume <runId>
```
## Important Notes
- **Always use `--agent` flag** for structured JSON output
- **Always call `one actions knowledge`** before adding an action step to a workflow
- Platform names are **kebab-case** (e.g., `hub-spot`, not `HubSpot`)
- Connection keys are **inputs**, not hardcoded — makes workflows portable and shareable
- Use `$.input.*` for input values, `$.steps.*` for step results
- Action IDs in examples (like `STRIPE_SEARCH_CUSTOMERS_ACTION_ID`) are placeholders — always use `one actions search` to find the real IDs
+3
-2
package.json
{
"name": "@withone/cli",
"version": "1.12.2",
"version": "1.12.3",
"description": "CLI for managing One",

@@ -8,3 +8,4 @@ "type": "module",

"bin",
"dist"
"dist",
"skills"
],

@@ -11,0 +12,0 @@ "bin": {

dist/index.js

Sorry, the diff of this file is too big to display