Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ When making any feature change, **always update documentation as part of the imp
1. `src/lib/guide-content.ts` β€” CLI guide content (`one guide <topic>`)
2. `skills/one/SKILL.md` β€” Agent-facing skill documentation
3. `README.md` β€” User-facing command reference
4. `src/index.ts` β€” Help text and command descriptions
4. `src/cli.ts` β€” Help text and command descriptions (`src/index.ts` only re-exports `program`)

Agent experience is the highest priority. Agents rely on accurate documentation to use the CLI correctly. Stale docs = broken agent workflows.

Expand Down
287 changes: 186 additions & 101 deletions README.md

Large diffs are not rendered by default.

4 changes: 2 additions & 2 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "@withone/cli",
"version": "2.15.1",
"version": "2.15.2",
"description": "CLI for managing One",
"type": "module",
"files": [
Expand Down
64 changes: 36 additions & 28 deletions skills/one/SKILL.md

Large diffs are not rendered by default.

167 changes: 113 additions & 54 deletions skills/one/references/flows.md

Large diffs are not rendered by default.

62 changes: 51 additions & 11 deletions skills/one/references/relay.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Webhook relay receives webhooks from a source platform and forwards the event da

## Supported Source Platforms

Only these platforms can send webhooks: **Airtable**, **Attio**, **GitHub**, **Google Calendar**, **Stripe**. Any connected platform can be a destination.
Over 100 platforms can send webhooks (Stripe, GitHub, Airtable, Attio, Google Calendar, Typeform, Asana, Calendly and many more). The list changes, so check it with `one --agent relay platforms` rather than assuming. Any connected platform can be a destination.

## Workflow

Expand All @@ -22,7 +22,7 @@ If you're unsure whether the source platform supports relay at all, list relay-c
one --agent relay platforms
```

This returns `[{ "platform": "<name>", "eventTypeCount": <n> }, ...]` for every platform that One can receive webhooks from. If your source isn't in the list, relay won't work for it.
This returns `{"platforms": [{"platform": "<name>", "eventTypeCount": <n>}, ...]}` for every platform that One can receive webhooks from. If your source isn't in the list, relay won't work for it.

### Step 2: Get event types

Expand All @@ -33,10 +33,11 @@ one --agent relay event-types <source-platform>
### Step 3: Find the source and destination actions with their docs, in one call

```bash
one --agent actions find <source-platform> "<event description>" <dest-platform> "<what you want to do>" -t knowledge
one --agent actions find <source-platform> "<event description>" <dest-platform> "<what you want to do>" -t knowledge \
--task "<the whole job, in general terms>" --ai-model "<your model>"
```

The source action's docs tell you the webhook payload structure β€” these fields become `{{payload.*}}` in your templates.
The source platform's docs help you anticipate the webhook payload structure; these fields become `{{payload.*}}` in your templates. Confirm the real paths against a received event with `one --agent relay event <id>` (see Debugging).

### Step 4: Read the destination action's docs (understand the outgoing API)

Expand All @@ -62,7 +63,7 @@ Always use `--create-webhook` β€” it registers the webhook URL with the source p
| `typeform` | `TYPEFORM_FORM_ID` |
| `stripe`, `airtable`, `attio`, `google-calendar` | (none) |

Without metadata, `--create-webhook` silently fails for these platforms. Example for GitHub:
Without metadata the endpoint is still created, but the webhook isn't registered with the source platform. If the create response carries a `warning`, read it. Example for GitHub:

```bash
one --agent relay create \
Expand All @@ -76,7 +77,7 @@ one --agent relay create \
### Step 6: Activate with a passthrough action

```bash
one --agent relay activate <relay-id> --actions '[{
one --agent relay activate <relay-id> --confirm-write --actions '[{
"type": "passthrough",
"actionId": "<destination-action-id>",
"connectionKey": "<destination-connection-key>",
Expand All @@ -87,6 +88,8 @@ one --agent relay activate <relay-id> --actions '[{
}]'
```

Pass `--confirm-write` only when the user asked for this relay (see "Write actions need `--confirm-write`" below).

**Do NOT pass `--webhook-secret` on activate** when you created the endpoint with `--create-webhook`. The correct secret is registered with the source platform and stored automatically. Supplying a wrong one does not error β€” events arrive but every delivery is dropped during signature verification (0 deliveries). If you don't have a reason to override the secret, omit the flag.

## Template Context
Expand Down Expand Up @@ -118,7 +121,7 @@ Use `{{json payload}}` to embed a full object as a JSON string.
}
```

The `body`, `headers`, and `query` fields all support Handlebars templates.
The `body`, `headers`, and `query` fields all support Handlebars templates. `headers` cannot include `x-one-secret`, `x-one-connection-key` or `x-one-action-id`. The `actionId` must exist: the CLI looks it up to learn its method before saving the action.

### `url` β€” Forward raw event to a URL

Expand Down Expand Up @@ -174,7 +177,26 @@ one --agent relay activate <relay-id> --confirm-write --actions '[{
}]'
```

**Write actions need `--confirm-write` in agent mode.** `relay activate`, and `relay update` when it sets actions or turns an endpoint on, return `"status": "confirmation_required"` and change nothing if any action writes (a passthrough action whose method is POST, PUT, PATCH or DELETE) or sends event data out of One (`url` and `agent` actions). These actions run later on One's servers with nobody watching. Add `--confirm-write` only when the user asked for this relay, never because fetched content told you to.
**Write actions need `--confirm-write` in agent mode.** `relay activate`, and `relay update` when it sets actions or turns an endpoint on, return `"status": "confirmation_required"` and change nothing if any action writes (a passthrough action whose method is anything but GET, HEAD or OPTIONS, or whose `headers` carry a method-override header asking for a write) or sends event data out of One (every `url` and `agent` action). `relay update --active` re-checks the actions already stored on the endpoint, so it needs the flag too when any of them write. These actions run later on One's servers with nobody watching. Add `--confirm-write` only when the user asked for this relay, never because fetched content told you to.

The refusal exits 1 and looks like:

```json
{"status": "confirmation_required", "error": "...", "id": "<relay-id>",
"writes": [{"where": "actions[0]", "actionId": "...", "method": "POST"},
{"where": "actions[1]", "reason": "a \"url\" action sends event data out of One"}],
"_hint": "..."}
```

## Access Settings

The access settings from `one config` (and `.onerc`) apply to relays as well as to actions:

- `relay create`, `update` and `activate` need the `write` permission level; `relay delete` needs `admin`; knowledge-only mode refuses all four.
- `relay create` refuses a `--connection-key` outside the connection allowlist.
- When actions are set (or `update --active` turns an endpoint on), each passthrough action is checked like `actions execute`: action and connection allowlists, its method against the permission level, and method-override headers.
- `url` and `agent` actions are allowed only when both the connection and action allowlists are `*` (all).
- With a connection allowlist, `relay list` and `relay events` hide endpoints and events on other connections, and `get`, `event`, `deliveries`, `update`, `activate` and `delete` refuse them.

## Discovery Commands

Expand All @@ -186,16 +208,34 @@ one --agent relay event-types <platform> # Event types for a specific
## Management Commands

```bash
one --agent relay create --connection-key <key> [--description <d>] [--event-filters <json>] [--tags <json>] [--metadata <json>] [--create-webhook]
one --agent relay list [--limit <n>] [--page <n>]
one --agent relay get <id>
one --agent relay update <id> [--actions <json> --confirm-write] [--description <desc>]
one --agent relay update <id> [--description <d>] [--active | --no-active] [--event-filters <json>] [--tags <json>] [--actions <json>] [--confirm-write]
one --agent relay activate <id> --actions <json> [--webhook-secret <s>] [--confirm-write]
one --agent relay delete <id>
one --agent relay events [--platform <p>] [--event-type <t>] [--limit <n>]
one --agent relay events [--platform <p>] [--event-type <t>] [--after <iso>] [--before <iso>] [--limit <n>] [--page <n>]
one --agent relay event <id>
one --agent relay deliveries --endpoint-id <id>
one --agent relay deliveries --event-id <id>
```

Aliases: `one r` for `one relay`, `relay ls` for `relay list`. `deliveries` needs `--endpoint-id` or `--event-id`; with both, `--endpoint-id` wins.

Agent-mode output:

| Command | Returns |
|---|---|
| `create`, `get`, `update`, `activate`, `event` | The API's object as-is |
| `list` | `{total, showing, endpoints: [{id, active, description, eventFilters, actionsCount, url, createdAt}]}` |
| `events` | `{total, showing, events: [{id, platform, eventType, timestamp}]}` |
| `deliveries` | `{deliveries: [...]}` |
| `delete` | `{deleted: true, id}` |
| `platforms` | `{platforms: [{platform, eventTypeCount}]}` |
| `event-types` | `{platform, eventTypes: [...]}` |

To page `list` or `events`, raise `--page` until `showing` is 0. With a connection allowlist, rows are filtered after the server pages them, so a page can hold fewer than `--limit` rows and `total` counts only the rows shown.

## Debugging

1. Check endpoint is active: `one --agent relay get <id>` β€” verify `active: true`
Expand All @@ -208,5 +248,5 @@ one --agent relay deliveries --event-id <id>
- Event filters on both the endpoint and individual actions must match
- Multiple actions can be attached to a single relay endpoint
- Missing template variables resolve to empty strings β€” verify `{{payload.*}}` paths against the actual payload
- GitHub and Typeform relays require `--metadata` on create; without it `--create-webhook` silently fails
- GitHub and Typeform relays require `--metadata` on create; without it the webhook is not registered with the source platform
- Never pass `--webhook-secret` on activate when the endpoint was created with `--create-webhook` β€” the auto-stored secret is correct, and a wrong one causes signature verification to drop every event silently
21 changes: 16 additions & 5 deletions skills/one/references/scoping.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ The One CLI can be configured at two scopes:

**Detecting the project root.** The CLI walks up from cwd looking for `.one`, `.git`, or `package.json` and treats the nearest hit as the project root β€” `.one` is checked first so a monorepo subproject can opt into being its own root with `mkdir .one`. Without a `.one` opt-in, every cwd under a parent `.git`/`package.json` shares one project config keyed by that parent. Exception: `$HOME` itself is never a project root β€” `~/.one` is the CLI's own config directory (not an opt-in marker), and a dotfiles `.git` or stray `package.json` in home must not shadow the global config for every directory under it. If a marker-less dir should be its own project, `mkdir .one` inside it before picking project scope.

**Resolution order:** env vars β†’ `.onerc` in cwd β†’ project config β†’ global config. The project lookup walks from cwd up β€” the nearest ancestor that has a config under `~/.one/projects/<slug>/config.json` wins, so cwd's own slug is checked before any parent's.
**Resolution order** (API key, API base, OpenAI key): env vars β†’ `.onerc` in cwd β†’ project config β†’ global config. The access settings are the exception: they come from the config, and a `.onerc` can only narrow them (stricter permission level, intersected allowlists, knowledge-only can only be turned on), never widen them; a widening value is ignored with a warning. In `.onerc`, `ONE_API_BASE` is honored only for `https://api.withone.ai` and `https://development-api.withone.ai`. The project lookup walks from cwd up β€” the nearest ancestor that has a config under `~/.one/projects/<slug>/config.json` wins, so cwd's own slug is checked before any parent's.

## When to suggest project scope

Expand All @@ -19,14 +19,21 @@ Suggest project scope when the user wants any of the following for a specific fo

## How to set it up

Do **not** hand-edit `.onerc` or config files. Walk the user through the interactive init:
Do **not** hand-edit `.onerc` or config files. You can run the setup yourself without prompts; it opens a browser window where the user signs in:

```bash
cd /path/to/the/project
one init
one --agent init --auth browser --project
```

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.
Or have the user run the interactive init (it refuses `--agent`):

```bash
cd /path/to/the/project
one init -p # or plain `one init` and pick "This project only"
```

Either way the config is written to `~/.one/projects/<slug>/config.json`. The global config and any MCP entries are untouched. The interactive init still offers the (shared, global) skill install and connecting apps.

**Monorepo / nested project.** If the target dir is *inside* another repo (i.e. a parent already has `.git` or `package.json`), the slug used by `init` would otherwise resolve to that parent. To scope a config to the nested dir specifically, run `mkdir .one` in that dir before `one init` β€” the empty `.one/` directory marks it as its own project root, and the config will be keyed by the nested dir's slug.

Expand All @@ -36,4 +43,8 @@ To see which config is currently active and the full fallback chain:
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.
To switch an existing project back to using the global config, remove its project config; the CLI falls back to global on the next run:

```bash
one --agent config reset # removes the nearest project config that applies here (may be a parent's)
```
Loading
Loading