OutlitAI · leo-paz · Jun 29, 2026 · Jun 29, 2026 · Jun 29, 2026
diff --git a/.changeset/platform-create-update-commands.md b/.changeset/platform-create-update-commands.md
@@ -0,0 +1,5 @@
+---
+"@outlit/cli": patch
+---
+
+Add resource-first platform action CLI commands for agent create/update, automation create/update, signal create/update, and destination create/update.
diff --git a/docs/ai-integrations/mcp.mdx b/docs/ai-integrations/mcp.mdx
@@ -1,6 +1,6 @@
 ---
 title: "MCP Integration"
-description: "Connect remote MCP clients to Outlit with your workspace URL and OAuth"
+description: "Connect remote MCP clients to Outlit with your workspace URL, OAuth, or scoped API keys"
 ---
 
 ## What is the Outlit MCP Server?
@@ -11,11 +11,13 @@ The Outlit CLI is not required for MCP setup. Use the workspace MCP URL directly
 
 ## Authentication Model
 
-Outlit's remote MCP endpoint uses OAuth-based authentication. In practice that means:
+Outlit's remote MCP endpoint uses OAuth-based authentication for customer-intelligence tools. In practice that means:
 - you add the workspace MCP URL to your client
 - you do not paste API keys or bearer headers into config files
 - the client opens an OAuth sign-in flow and stores the resulting session
 
+Platform configuration tools use API-key authentication today. Use an API key with `agents:read` for read-only configuration tools and `agents:write` for write tools.
+
 ## Connect Your MCP Client
 
 <Steps>
@@ -43,7 +45,7 @@ Outlit's remote MCP endpoint uses OAuth-based authentication. In practice that m
     }
     ```
 
-    No `Authorization` header is needed.
+    No `Authorization` header is needed for OAuth-based customer-intelligence tools.
   </Step>
   <Step title="Complete OAuth in the client">
     After you add the server, your client should prompt you to sign in to Outlit and authorize access for that workspace.
@@ -61,6 +63,43 @@ Outlit's remote MCP endpoint uses OAuth-based authentication. In practice that m
   Use [Agent Skills](/ai-integrations/skills) for coding agents like Claude Code, Codex, and Gemini CLI. Use MCP when your primary surface is an MCP client such as Cursor, VS Code, or another remote-MCP connector.
 </Tip>
 
+## Platform Configuration Over MCP
+
+Platform configuration tools inspect and mutate agents, automations, signals, and destinations. These tools require API-key authentication because they execute scoped platform actions.
+
+<Steps>
+  <Step title="Create a scoped API key">
+    Open [Settings > CLI & MCP](https://app.outlit.ai/settings/workspace/mcp) and create an API key for agent configuration. The key must include `agents:read` for read tools and `agents:write` for write tools.
+  </Step>
+  <Step title="Add the bearer header in supported clients">
+    For MCP clients that support custom headers or headless bearer-token setup, configure the same workspace MCP URL with an `Authorization` header:
+
+    ```json
+    {
+      "mcpServers": {
+        "outlit": {
+          "url": "https://mcp.outlit.ai/w/<workspace-slug>/mcp",
+          "headers": {
+            "Authorization": "Bearer ok_your_api_key"
+          }
+        }
+      }
+    }
+    ```
+  </Step>
+  <Step title="Verify platform tools">
+    Ask your client:
+
+    ```text
+    List my Outlit agent templates.
+    ```
+  </Step>
+</Steps>
+
+<Note>
+  Do not add API keys to OAuth-only client configs. If your MCP client cannot send bearer headers, use the CLI or REST API for platform configuration actions.
+</Note>
+
 ## What Tools Are Available?
 
 | Tool | What it does | Example prompt |
@@ -93,20 +132,27 @@ API-key authenticated MCP clients can also inspect and manage selected agent and
 | `outlit_agent_list_available_actions` | List available agent configuration actions |
 | `outlit_agent_list` | List configured agents |
 | `outlit_agent_get` | Get one configured agent |
-| `outlit_agent_create_from_template` | Create supported template resources in draft mode |
+| `outlit_agent_create` | Create an agent |
+| `outlit_agent_update` | Update one configured agent |
 | `outlit_agent_enable` | Enable one configured agent |
 | `outlit_agent_disable` | Disable one configured agent |
 | `outlit_agent_rename` | Rename one configured agent |
 | `outlit_automation_list` | List configured automations |
 | `outlit_automation_get` | Get one configured automation |
+| `outlit_automation_create` | Create an agent automation from an `agentId` |
+| `outlit_automation_update` | Update an agent automation from an `agentId` |
 | `outlit_automation_enable` | Enable one configured automation |
 | `outlit_automation_disable` | Disable one configured automation |
 | `outlit_automation_archive` | Archive one configured automation |
 | `outlit_signal_list` | List configured automation signals |
 | `outlit_signal_get` | Get one configured automation signal |
+| `outlit_signal_create` | Create one automation signal |
+| `outlit_signal_update` | Update one automation signal |
 | `outlit_signal_archive` | Archive one configured automation signal |
 | `outlit_destination_list` | List configured automation destinations with masked configuration |
 | `outlit_destination_get` | Get one configured automation destination with masked configuration |
+| `outlit_destination_create` | Create one automation destination |
+| `outlit_destination_update` | Update one automation destination |
 | `outlit_destination_enable` | Enable one configured automation destination |
 | `outlit_destination_disable` | Disable one configured automation destination |
 | `outlit_destination_archive` | Archive one configured automation destination |

diff --git a/docs/ai-integrations/platform-actions.mdx b/docs/ai-integrations/platform-actions.mdx
@@ -17,27 +17,46 @@ Use platform actions for Outlit-hosted agents, automations, signals, and destina
 
 Each surface calls the same platform action contracts. The transport changes, but the intent does not: the API exposes the canonical route, the CLI wraps that route for terminal use, and MCP exposes the same operation as an agent tool.
 
+## Naming Model
+
+Platform actions use resource-first names so humans and agents can predict what to call next:
+
+| Surface | Pattern | Example |
+|---------|---------|---------|
+| CLI | `outlit <resource> <verb>` | `outlit agents update <id> --instructions "..."`
+| REST API | Standard resource routes | `PATCH /api/agents/{id}` |
+| MCP | `<resource>_<verb>` tool names | `outlit_agent_update` |
+
+Subtypes and templates are inputs, not command names. For example, use `outlit agents create --template churn` to create a template-backed agent, and use `outlit destinations create --type webhook` to create a webhook destination.
+
+Agent and destination updates patch only the fields provided. Automation and signal updates currently take full configuration bodies, so agents should read the current resource first, preserve fields they do not intend to change, and then send the updated body.
+
 ## Current Scope
 
 The current platform action set focuses on the Agents and Automations areas of the Outlit platform.
 
 | Area | Read actions | Write actions |
 |------|--------------|---------------|
-| Agents | List templates, list available actions, list agents, get one agent | Create a supported agent template draft, enable, disable, rename |
-| Automations | List automations, get one automation | Enable, disable, archive |
-| Signals | List configured automation signals, get one signal | Archive |
-| Destinations | List configured destinations, get one destination with masked configuration | Enable, disable, archive |
+| Agents | List templates, list available actions, list agents, get one agent | Create, update, enable, disable, rename |
+| Automations | List automations, get one automation | Create, update, enable, disable, archive |
+| Signals | List configured automation signals, get one signal | Create, update, archive |
+| Destinations | List configured destinations, get one destination with masked configuration | Create, update, enable, disable, archive |
 
 For example, a CLI user or agent can create a draft template and then explicitly enable or disable lifecycle resources:
 
 ```bash
-outlit agents create-from-template churn --json
-outlit agents enable agent_123 --json
+outlit agents create --template churn --json
+outlit agents create --type custom --display-name "Renewal risk" --instructions "Find risk" --surface-criteria "Surface risky customers" --json
+outlit signals create --file ./signal.json --json
+outlit automations create --file ./automation.json --json
+outlit agents enable 10000000-0000-4000-8000-000000000004 --json
 outlit automations disable 10000000-0000-4000-8000-000000000001 --json
 ```
 
 Template creation creates supported template resources in `draft` mode. Draft creation does not enable an automation, add schedules, add external destinations, or send notifications by itself. Lifecycle write actions mutate only the named resource state.
 
+Automation create and update actions are agent-centered. Callers provide `agentId`; update bodies also provide `name`, `enabled`, and `triggerType` explicitly. Outlit maps the agent ID to the hosted-agent processor internally and does not require callers to construct raw processor JSON.
+
 ## Safety Model
 
 Platform actions are designed to make configuration inspectable before they make it broadly mutable.
@@ -69,8 +88,11 @@ A coding agent or MCP client can use platform actions to inspect what exists, ch
 ```bash
 outlit agents templates --json
 outlit agents actions --json
-outlit agents create-from-template churn --json
-outlit agents enable agent_123 --json
+outlit agents create --template churn --json
+outlit agents update 10000000-0000-4000-8000-000000000004 --instructions "Prioritize recent support escalations" --json
+outlit destinations create --type webhook --name "Customer ops" --url https://hooks.example.com/outlit --json
+outlit destinations update 10000000-0000-4000-8000-000000000003 --type webhook --name "Customer ops" --json
+outlit agents enable 10000000-0000-4000-8000-000000000004 --json
 outlit agents list --json
 outlit automations list --json
 outlit automations enable 10000000-0000-4000-8000-000000000001 --json
@@ -88,20 +110,27 @@ This workflow lets the agent discover available templates, understand supported
 | `GET /api/agent-actions` | List available agent configuration actions |
 | `GET /api/agents` | List configured agents |
 | `GET /api/agents/{id}` | Get one configured agent |
-| `POST /api/agents` | Create an agent from a supported template |
+| `POST /api/agents` | Create an agent |
+| `PATCH /api/agents/{id}` | Update one configured agent |
 | `POST /api/agents/{id}/enable` | Enable one configured agent |
 | `POST /api/agents/{id}/disable` | Disable one configured agent |
 | `POST /api/agents/{id}/rename` | Rename one configured agent |
 | `GET /api/automations` | List configured automations |
+| `POST /api/automations` | Create an agent automation |
 | `GET /api/automations/{id}` | Get one configured automation |
+| `PATCH /api/automations/{id}` | Update one agent automation |
 | `POST /api/automations/{id}/enable` | Enable one configured automation |
 | `POST /api/automations/{id}/disable` | Disable one configured automation |
 | `POST /api/automations/{id}/archive` | Archive one configured automation |
 | `GET /api/signals` | List configured automation signals |
+| `POST /api/signals` | Create one automation signal |
 | `GET /api/signals/{id}` | Get one configured automation signal |
+| `PATCH /api/signals/{id}` | Update one automation signal |
 | `POST /api/signals/{id}/archive` | Archive one configured automation signal |
 | `GET /api/destinations` | List configured automation destinations with masked configuration |
 | `GET /api/destinations/{id}` | Get one configured automation destination with masked configuration |
+| `POST /api/destinations` | Create one automation destination |
+| `PATCH /api/destinations/{id}` | Update one automation destination |
 | `POST /api/destinations/{id}/enable` | Enable one configured automation destination |
 | `POST /api/destinations/{id}/disable` | Disable one configured automation destination |
 | `POST /api/destinations/{id}/archive` | Archive one configured automation destination |

diff --git a/docs/cli/commands.mdx b/docs/cli/commands.mdx
@@ -562,7 +562,8 @@ outlit agents list [flags]
 outlit agents get <id> [flags]
 outlit agents templates [flags]
 outlit agents actions [flags]
-outlit agents create-from-template churn [flags]
+outlit agents create [flags]
+outlit agents update <id> [flags]
 outlit agents enable <id> [flags]
 outlit agents disable <id> [flags]
 outlit agents rename <id> <display-name> [flags]
@@ -572,17 +573,22 @@ outlit agents rename <id> <display-name> [flags]
 
 ```bash
 outlit agents list --json
-outlit agents get agent_123 --json
+outlit agents get 10000000-0000-4000-8000-000000000004 --json
 outlit agents templates --json
 outlit agents actions --json
-outlit agents create-from-template churn --json
-outlit agents enable agent_123 --json
-outlit agents disable agent_123 --json
-outlit agents rename agent_123 "Churn prevention" --json
+outlit agents create --template churn --json
+outlit agents create --type custom --display-name "Renewal risk" --instructions "Find risk" --surface-criteria "Surface risky customers" --json
+outlit agents update 10000000-0000-4000-8000-000000000004 --display-name "Renewal risk" --json
+outlit agents update 10000000-0000-4000-8000-000000000004 --instructions "Prioritize recent escalations" --json
+outlit agents update 10000000-0000-4000-8000-000000000004 --action-keys send_slack_notification --json
+outlit agents update 10000000-0000-4000-8000-000000000004 --clear-action-keys --json
+outlit agents enable 10000000-0000-4000-8000-000000000004 --json
+outlit agents disable 10000000-0000-4000-8000-000000000004 --json
+outlit agents rename 10000000-0000-4000-8000-000000000004 "Churn prevention" --json
 ```
 
 <Note>
-  `create-from-template` creates supported template resources in draft mode. `enable`, `disable`, and `rename` require an API key with `agents:write`.
+  `agents create --template` creates supported template resources in draft mode. `agents update` patches only the fields you pass. Use `--clear-action-keys` to remove all action keys. Agent write commands require an API key with `agents:write`.
 </Note>
 
 ## Automations
@@ -592,6 +598,10 @@ Inspect configured platform automations.
 ```bash
 outlit automations list [flags]
 outlit automations get <id> [flags]
+outlit automations create --data <json> [flags]
+outlit automations create --file <path> [flags]
+outlit automations update <id> --data <json> [flags]
+outlit automations update <id> --file <path> [flags]
 outlit automations enable <id> [flags]
 outlit automations disable <id> [flags]
 outlit automations archive <id> [flags]
@@ -602,22 +612,30 @@ outlit automations archive <id> [flags]
 ```bash
 outlit automations list --json
 outlit automations get 10000000-0000-4000-8000-000000000001 --json
+outlit automations create --file ./automation.json --json
+outlit automations update 10000000-0000-4000-8000-000000000001 --file ./automation.json --json
 outlit automations enable 10000000-0000-4000-8000-000000000001 --json
 outlit automations disable 10000000-0000-4000-8000-000000000001 --json
 outlit automations archive 10000000-0000-4000-8000-000000000001 --json
 ```
 
+Automation create bodies must include `agentId`, `name`, and `triggerType`. Update bodies must include `agentId`, `name`, `enabled`, and `triggerType`. The API maps that agent ID to the internal hosted-agent processor; callers do not provide raw processor JSON.
+
 ### JSON Response
 
-Automation commands return command envelopes. List results are under `result.data.automations`; get, enable, and disable results are under `result.data.automation`. Archive results return `result.data.automation.id` and `result.data.automation.archivedAt`.
+Automation commands return command envelopes. List results are under `result.data.automations`; get, create, update, enable, and disable results are under `result.data.automation`. Archive results return `result.data.automation.id` and `result.data.automation.archivedAt`.
 
 ## Signals
 
-Inspect and archive configured automation signals.
+Inspect and configure automation signals.
 
 ```bash
 outlit signals list [flags]
 outlit signals get <id> [flags]
+outlit signals create --data <json> [flags]
+outlit signals create --file <path> [flags]
+outlit signals update <id> --data <json> [flags]
+outlit signals update <id> --file <path> [flags]
 outlit signals archive <id> [flags]
 ```
 
@@ -626,10 +644,12 @@ outlit signals archive <id> [flags]
 ```bash
 outlit signals list --json
 outlit signals get 10000000-0000-4000-8000-000000000002 --json
+outlit signals create --file ./signal.json --json
+outlit signals update 10000000-0000-4000-8000-000000000002 --file ./signal.json --json
 outlit signals archive 10000000-0000-4000-8000-000000000002 --json
 ```
 
-Signal list results are under `result.data.signals`; get results are under `result.data.signal`. Archive results return `result.data.signal.id` and `result.data.signal.archivedAt`.
+Signal list results are under `result.data.signals`; get, create, and update results are under `result.data.signal`. Archive results return `result.data.signal.id` and `result.data.signal.archivedAt`.
 
 ## Destinations
 
@@ -638,6 +658,8 @@ Inspect and manage configured automation destinations with masked configuration
 ```bash
 outlit destinations list [flags]
 outlit destinations get <id> [flags]
+outlit destinations create [flags]
+outlit destinations update <id> [flags]
 outlit destinations enable <id> [flags]
 outlit destinations disable <id> [flags]
 outlit destinations archive <id> [flags]
@@ -648,12 +670,14 @@ outlit destinations archive <id> [flags]
 ```bash
 outlit destinations list --json
 outlit destinations get 10000000-0000-4000-8000-000000000003 --json
+outlit destinations create --type webhook --name "Customer ops" --url https://hooks.example.com/outlit --json
+outlit destinations update 10000000-0000-4000-8000-000000000003 --type webhook --name "Customer ops" --json
 outlit destinations enable 10000000-0000-4000-8000-000000000003 --json
 outlit destinations disable 10000000-0000-4000-8000-000000000003 --json
 outlit destinations archive 10000000-0000-4000-8000-000000000003 --json
 ```
 
-Destination list results are under `result.data.destinations`; get, enable, and disable results are under `result.data.destination`. Archive results return `result.data.destination.id` and `result.data.destination.archivedAt`. Raw destination secrets and unmasked provider configuration are not returned.
+Destination list results are under `result.data.destinations`; get, create, update, enable, and disable results are under `result.data.destination`. `destinations update` patches only the fields you pass. Archive results return `result.data.destination.id` and `result.data.destination.archivedAt`. Raw destination secrets and unmasked provider configuration are not returned.
 
 ## SQL