@pixelml/agenticflow-cli 1.6.1 → 1.6.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (11) hide show
  1. package/README.md +153 -124
  2. package/dist/cli/changelog.d.ts.map +1 -1
  3. package/dist/cli/changelog.js +29 -0
  4. package/dist/cli/changelog.js.map +1 -1
  5. package/dist/cli/main.d.ts.map +1 -1
  6. package/dist/cli/main.js +35 -14
  7. package/dist/cli/main.js.map +1 -1
  8. package/dist/cli/playbooks.d.ts.map +1 -1
  9. package/dist/cli/playbooks.js +11 -1
  10. package/dist/cli/playbooks.js.map +1 -1
  11. package/package.json +1 -1
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # AgenticFlow CLI
2
2
 
3
- Command-line interface for AI agents and developers to interact with the [AgenticFlow](https://agenticflow.ai) platform — build agents, deploy them to external platforms, and receive tasks from any webhook source.
3
+ Command-line interface for AI agents and developers to operate the [AgenticFlow](https://agenticflow.ai) platform — build agents, deploy multi-agent workforces, and integrate with MCP tool providers, all from your shell.
4
4
 
5
5
  [![npm](https://img.shields.io/npm/v/@pixelml/agenticflow-cli)](https://www.npmjs.com/package/@pixelml/agenticflow-cli)
6
6
 
@@ -18,194 +18,214 @@ Requires Node.js 18+. The CLI is available as both `agenticflow` and `af` (short
18
18
  # 1. Authenticate
19
19
  af login
20
20
 
21
- # 2. Verify setup
22
- af doctor --json
21
+ # 2. One-shot orientation — auth, agents, workforces, blueprints, playbooks, what's new
22
+ af bootstrap --json
23
23
 
24
- # 3. List your agents
25
- af agent list --fields id,name,model --json
24
+ # 3. Talk to an existing agent
25
+ af agent run --agent-id <id> --message "Hello!" --json
26
26
 
27
- # 4. Talk to an agent
28
- af agent stream --agent-id <id> --body '{"messages":[{"content":"Hello!"}]}'
27
+ # 4. Or deploy a ready-made team in one command (v1.6+)
28
+ af workforce init --blueprint dev-shop --name "My Dev Team" --json
29
29
  ```
30
30
 
31
- > **AI agents**: Run `af context --json` for a machine-readable bootstrap guide with invariants, schemas, and discovery links.
31
+ > **AI agents**: start every session with `af bootstrap --json` — it returns everything in one call. See the [AI Agent Context](CONTEXT.md) guide.
32
+
33
+ ## What you can build
34
+
35
+ | You want… | Use | Because |
36
+ |---|---|---|
37
+ | A single chat endpoint / customer-facing bot / one assistant | **`af agent create`** then `af agent run` | One prompt handles routing. Iterate with `af agent update --patch` |
38
+ | Multiple agents that hand off (research → write, triage → specialist, dev shop, marketing agency, Amazon seller team, …) | **`af workforce init --blueprint <id>`** | Creates workforce + N agents + wired DAG in one command. Atomic rollback on failure |
39
+ | A DAG of prompt/tool/logic nodes (not necessarily multi-agent) | **`af workflow create`** then `af workflow run` | Classic workflow engine |
40
+ | Attach Google Docs/Sheets/Slack/Notion to an agent | **`af mcp-clients list/inspect`** then `af agent update --patch` | Inspect before attach to avoid Pipedream write-capability traps |
41
+
42
+ Don't reach for a workforce when a single agent suffices — the 6 built-in workforce blueprints are for genuine multi-agent orchestration (dev-shop, marketing-agency, sales-team, content-studio, support-center, amazon-seller).
32
43
 
33
44
  ## Authentication
34
45
 
35
46
  | Method | Usage | Best For |
36
- |--------|-------|----------|
37
- | **Interactive login** | `af login` | First-time setup |
38
- | **Environment variable** | `export AGENTICFLOW_API_KEY=<key>` | CI/CD, automated agents |
39
- | **CLI flag** | `--api-key <key>` | One-off scripts |
40
- | **Import from .env** | `af auth import-env --file .env` | Batch import |
47
+ |---|---|---|
48
+ | Interactive login | `af login` | First-time setup |
49
+ | Environment variable | `export AGENTICFLOW_API_KEY=<key>` | CI/CD, automated agents |
50
+ | CLI flag | `--api-key <key>` | One-off scripts |
51
+ | Import from `.env` | `af auth import-env --file .env` | Batch import |
41
52
 
42
53
  ```bash
43
- af login # Interactive setup (saves to ~/.agenticflow/auth.json)
54
+ af login # Saves to ~/.agenticflow/auth.json
44
55
  af whoami --json
45
- af doctor --json --strict
56
+ af doctor --json --strict # Preflight with explicit exit codes
46
57
  ```
47
58
 
48
59
  ### Environment Variables
49
60
 
50
61
  | Variable | Purpose |
51
- |----------|---------|
62
+ |---|---|
52
63
  | `AGENTICFLOW_API_KEY` | API key |
53
64
  | `AGENTICFLOW_WORKSPACE_ID` | Default workspace ID |
54
65
  | `AGENTICFLOW_PROJECT_ID` | Default project ID |
55
- | `PAPERCLIP_URL` | Paperclip instance URL (default: http://localhost:3100) |
56
- | `PAPERCLIP_COMPANY_ID` | Default Paperclip company |
57
- | `LINEAR_API_KEY` | Linear API key (for gateway) |
58
- | `LINEAR_AGENT_MAP` | JSON team→agent mapping (for gateway) |
59
-
60
- ## Commands
66
+ | `AF_SILENCE_DEPRECATIONS=1` | Suppress `af paperclip` deprecation warnings while migrating |
67
+ | `AF_INSECURE_TLS=1` | Opt-in to insecure TLS for self-signed dev backends (off by default — CLI unsets inherited `NODE_TLS_REJECT_UNAUTHORIZED=0`) |
68
+ | `PAPERCLIP_URL` | Paperclip URL (deprecated — sunset 2026-10-14) |
69
+ | `LINEAR_API_KEY` / `LINEAR_AGENT_MAP` | Linear gateway config |
61
70
 
62
- ### AI-Agent Discovery
71
+ ## AI-Agent Discovery
63
72
 
64
73
  ```bash
65
- af context --json # Bootstrap guide for AI agents (start here)
66
- af schema # List all resource schemas
67
- af schema agent # Agent payload schema with examples
68
- af schema paperclip.issue # Paperclip issue schema
69
- af discover --json # Full CLI capability index
70
- af playbook --list # Guided playbooks
74
+ af bootstrap --json # THE one-shot orientation — start here
75
+ af context --json # AI-agent usage guide (invariants, schemas)
76
+ af schema # List all resource schemas
77
+ af schema agent # Agent create/update/stream shape
78
+ af schema agent --field mcp_clients # Drill into a specific field (v1.5.1+)
79
+ af schema workforce --field schema # Workforce graph shape (nodes + edges)
80
+ af playbook # List all guided playbooks
81
+ af playbook first-touch # Zero-to-working-agent walkthrough
82
+ af changelog --json # What changed after an upgrade
71
83
  ```
72
84
 
85
+ ## Core Commands
86
+
73
87
  ### Agents
74
88
 
75
89
  ```bash
76
- af agent list --fields id,name,model --json # List (with field filter)
90
+ af agent list --fields id,name,model --json
91
+ af agent list --name-contains silk --fields id,name --json # v1.5.1+ client-side filter
77
92
  af agent get --agent-id <id> --json
78
- af agent create --body @agent.json --dry-run # Validate first
79
- af agent create --body @agent.json # Create
80
- af agent update --agent-id <id> --body @update.json
81
- af agent delete --agent-id <id>
82
- af agent stream --agent-id <id> --body @stream.json
93
+ af agent create --body @agent.json --dry-run --json # Validate first
94
+ af agent create --body @agent.json --json
95
+ af agent update --agent-id <id> --patch --body '{"system_prompt":"..."}' # v1.5.0+ partial update (fetch → merge → PUT)
96
+ af agent delete --agent-id <id> --json
97
+ af agent run --agent-id <id> --message "..." --json # Non-streaming (returns {response, thread_id})
98
+ af agent run --agent-id <id> --thread-id <tid> --message "continue..."
99
+ af agent stream --agent-id <id> --body @messages.json # SSE streaming
83
100
  ```
84
101
 
85
- ### Workflows
102
+ `af agent update --patch` (v1.5.0+) is the recommended iteration path — send only the field you want to change; MCP clients, tools, and other config stay intact.
103
+
104
+ ### Workforces (v1.5.0+) — the native multi-agent deploy
86
105
 
87
106
  ```bash
88
- af workflow list --fields id,name,status --json
89
- af workflow get --workflow-id <id> --json
90
- af workflow create --body @wf.json --dry-run # Validate first
91
- af workflow create --body @wf.json
92
- af workflow run --workflow-id <id> --input @input.json
93
- af workflow run-status --workflow-run-id <run_id> --json
94
- af workflow validate --body @wf.json --local-only
107
+ af workforce init --blueprint <slug> --name "My Team" --dry-run --json # Preview
108
+ af workforce init --blueprint <slug> --name "My Team" --json # Create workforce + agents + wired DAG, atomic rollback on failure
109
+
110
+ af workforce list --fields id,name --json
111
+ af workforce schema --workforce-id <id> --json # Full graph (nodes + edges)
112
+ af workforce deploy --workforce-id <id> --body @graph.json --json # Atomic graph replace
113
+ af workforce validate --workforce-id <id> --json # Cycle detection
114
+ af workforce run --workforce-id <id> --trigger-data '{"message":"..."}' # SSE stream
115
+ af workforce versions list --workforce-id <id> --json
116
+ af workforce versions publish --workforce-id <id> --version-id <v>
117
+ af workforce publish --workforce-id <id> --json # Public key + URL
118
+ af workforce delete --workforce-id <id> --json
95
119
  ```
96
120
 
97
- ### Webhook Gateway
121
+ Blueprints: `dev-shop` (4), `marketing-agency` (4), `sales-team` (3), `content-studio` (4), `support-center` (3), `amazon-seller` (5). Each `af workforce init --blueprint <id>` creates one agent per non-optional slot, wires the graph (trigger → coordinator → worker agents → output), and returns the `workforce_id` + every `agent_id` in one response.
98
122
 
99
- Receive tasks from any platform and route them to AgenticFlow agents:
123
+ ### MCP Clients
100
124
 
101
125
  ```bash
102
- # Start the gateway
103
- af gateway serve --channels paperclip,linear,webhook --verbose
104
-
105
- # Available channels
106
- af gateway channels
126
+ af mcp-clients list --name-contains "google sheets" --fields id,name --json # v1.5.2+
127
+ af mcp-clients list --verify-auth --json # Reconcile stale auth flags
128
+ af mcp-clients get --id <id> --json # `--client-id` also works
129
+ af mcp-clients inspect --id <id> --json # v1.5.1+ — classify Pipedream vs Composio, flag write quirks
107
130
  ```
108
131
 
109
- **Generic webhook** — send tasks from anywhere:
110
- ```bash
111
- curl -X POST http://localhost:4100/webhook/webhook \
112
- -H "Content-Type: application/json" \
113
- -d '{"agent_id":"<id>","message":"Summarize the Q4 report","callback_url":"https://..."}'
114
- ```
132
+ See `af playbook mcp-client-quirks` — some MCP providers break on parametric writes. Inspect before attaching.
115
133
 
116
- **Paperclip channel** — receive heartbeats from a Paperclip company:
117
- ```bash
118
- af gateway serve --channels paperclip --paperclip-url http://localhost:3100
119
- ```
134
+ ### Workflows
120
135
 
121
- **Linear channel** — process Linear issues:
122
136
  ```bash
123
- export LINEAR_API_KEY=lin_api_xxxxx
124
- export LINEAR_AGENT_MAP='{"ENG":"<af-agent-id>"}'
125
- af gateway serve --channels linear
137
+ af workflow list --fields id,name,status --json
138
+ af workflow get --workflow-id <id> --json
139
+ af workflow validate --body @wf.json --local-only
140
+ af workflow create --body @wf.json --json
141
+ af workflow run --workflow-id <id> --input @input.json
142
+ af workflow run-status --workflow-run-id <run_id> --json
126
143
  ```
127
144
 
128
- The gateway is also serverless-compatible via `createGatewayHandler()`.
129
-
130
- ### Paperclip Integration
131
-
132
- Deploy AgenticFlow agents to [Paperclip](https://github.com/paperclipai/paperclip) as HTTP-adapter workers:
145
+ ### Company (portable agent-bundle export/import)
133
146
 
134
147
  ```bash
135
- # Create a company
136
- af paperclip company create --name "My AI Company" --budget 100000
137
-
138
- # Deploy agents
139
- af paperclip deploy --agent-id <id> --role engineer
140
- af paperclip deploy --agent-id <id2> --role designer
148
+ af company export --output company-export.yaml
149
+ af company diff company-export.yaml --json # Phase 7 — field-level diff
150
+ af company import --merge company-export.yaml --conflict-strategy local
151
+ ```
141
152
 
142
- # Set goals and assign tasks
143
- af paperclip goal create --title "Build the product" --level company
144
- af paperclip issue create --title "Design landing page" --assignee <agent-id> --priority high
153
+ ### Paperclip (DEPRECATED — sunset 2026-10-14)
145
154
 
146
- # Connect agents to gateway and trigger work
147
- af gateway serve --channels paperclip
148
- af paperclip connect
149
- af paperclip agent wakeup --id <agent-id>
155
+ `af paperclip *` commands still work but emit a one-line deprecation warning per subcommand per session. Use `af playbook migrate-from-paperclip` for the command-by-command map. Silence with `AF_SILENCE_DEPRECATIONS=1` while migrating.
150
156
 
151
- # Monitor
152
- af paperclip dashboard
153
- af paperclip issue comments --id <issue-id>
154
- ```
157
+ ### Webhook Gateway
155
158
 
156
- Full Paperclip command reference:
157
- ```
158
- af paperclip company list|get|create|update|archive|delete
159
- af paperclip agent list|get|update|pause|resume|terminate|wakeup|delete
160
- af paperclip goal list|get|create|update|delete
161
- af paperclip issue list|get|create|update|assign|comment|comments|delete
162
- af paperclip approval list|approve|reject
163
- af paperclip dashboard
164
- af paperclip deploy --agent-id <id> [--role <role>]
165
- af paperclip connect
159
+ ```bash
160
+ af gateway serve --channels webhook,linear --verbose
161
+ af gateway channels
166
162
  ```
167
163
 
168
- ### Node Types
169
-
164
+ Send a task:
170
165
  ```bash
171
- af node-types search --query "llm" --json # Search by keyword
172
- af node-types get --name <name> --json # Get specific type
173
- af node-types list [--limit N] --json # List all (large)
166
+ curl -X POST http://localhost:4100/webhook/webhook \
167
+ -H "Content-Type: application/json" \
168
+ -d '{"agent_id":"<id>","message":"Do X","callback_url":"https://..."}'
174
169
  ```
175
170
 
176
- ### Connections
171
+ ### Node Types & Connections
177
172
 
178
173
  ```bash
174
+ af node-types search --query "llm" --json
175
+ af node-types get --name <type> --json
179
176
  af connections list --limit 200 --json
180
- af connections create --body @conn.json
181
- af connections update --connection-id <id> --body @update.json
182
- af connections delete --connection-id <id>
183
177
  ```
184
178
 
185
- ### Playbooks
179
+ ## Playbooks — guided paths
186
180
 
187
181
  ```bash
188
- af playbook quickstart # Zero to working agent in 5 minutes
189
- af playbook gateway-setup # Multi-channel webhook gateway
190
- af playbook deploy-to-paperclip # Full Paperclip company setup
191
- af playbook agent-channels # Connect Linear, webhooks, etc.
192
- af playbook agent-build # Agent configuration deep dive
193
- af playbook workflow-build # Workflow design checklist
194
- af playbook template-bootstrap # Start from pre-built templates
195
- af playbook mcp-to-cli-map # MCP → CLI command mapping
182
+ af playbook first-touch # AI-agent onboarding (START HERE)
183
+ af playbook quickstart # Zero → working agent in 5 minutes
184
+ af playbook agent-build # Agent configuration deep dive
185
+ af playbook workflow-build # Workflow design checklist
186
+ af playbook workflow-run # Execute + monitor workflows
187
+ af playbook amazon-seller # Full Amazon SG seller team deploy
188
+ af playbook company-from-scratch # Build an AI company step-by-step
189
+ af playbook migrate-from-paperclip # Paperclip → workforce command map (v1.5.0+)
190
+ af playbook mcp-client-quirks # Pipedream vs Composio — attach safety (v1.5.1+)
191
+ af playbook gateway-setup # Multi-channel webhook gateway
192
+ af playbook agent-channels # Connect Linear, webhooks, etc.
193
+ af playbook template-bootstrap # Start from pre-built templates
194
+ af playbook mcp-to-cli-map # MCP → CLI command mapping
195
+ af playbook deploy-to-paperclip # [DEPRECATED] legacy Paperclip deploy
196
196
  ```
197
197
 
198
198
  ## Global Options
199
199
 
200
200
  | Flag | Purpose |
201
- |------|---------|
202
- | `--json` | Machine-readable JSON output |
201
+ |---|---|
202
+ | `--json` | Machine-readable JSON output with `schema:` discriminators |
203
203
  | `--fields <fields>` | Filter output fields (saves context window) |
204
- | `--dry-run` | Validate without executing (on create commands) |
204
+ | `--dry-run` | Validate without executing (on create/deploy commands) |
205
+ | `--patch` | Partial update (on `af agent update` and other update commands) |
205
206
  | `--api-key <key>` | Override API key |
206
207
  | `--workspace-id <id>` | Override workspace |
207
208
  | `--project-id <id>` | Override project |
208
209
 
210
+ ## Error handling
211
+
212
+ Every `--json` error returns a consistent envelope:
213
+
214
+ ```json
215
+ {
216
+ "schema": "agenticflow.error.v1",
217
+ "code": "request_failed",
218
+ "message": "Request failed with status 404: Agent not found",
219
+ "hint": "Resource not found. Run the matching `list` command (e.g. `af agent list --json`) to see available IDs, or double-check the ID you passed.",
220
+ "details": {
221
+ "status_code": 404,
222
+ "payload": { "detail": "Agent not found" }
223
+ }
224
+ }
225
+ ```
226
+
227
+ Common codes: `local_schema_validation_failed`, `request_failed`, `operation_not_found`, `invalid_option_value`, `missing_required_option`, `workforce_init_failed`.
228
+
209
229
  ## SDK
210
230
 
211
231
  ```typescript
@@ -217,19 +237,28 @@ const client = createClient({
217
237
  projectId: process.env.AGENTICFLOW_PROJECT_ID,
218
238
  });
219
239
 
240
+ // Agents
220
241
  const agents = await client.agents.list();
221
- const result = await client.workflows.run("workflow-id", { query: "hello" });
242
+ await client.agents.patch(agentId, { system_prompt: "..." });
243
+
244
+ // Workforces (v1.5.0+)
245
+ const wf = await client.workforces.create({ name: "My Team" });
246
+ await client.workforces.putSchema(wf.id, { nodes, edges });
247
+ const stream = await client.workforces.run(wf.id, { trigger_data: { message: "..." } });
222
248
  ```
223
249
 
224
250
  ## Troubleshooting
225
251
 
226
252
  | Problem | Solution |
227
- |---------|----------|
228
- | `Invalid <field>: expected UUID` | Use a valid UUID from `af agent list --json` |
229
- | `Port 4100 already in use` | Kill existing gateway or use `--port 4101` |
230
- | `Connection X not found` | CLI auto-resolves via smart connection resolution |
231
- | `401 Error` | Run `af doctor --json` to check auth |
232
- | Connections list too few | Default limit is 10. Use `--limit 200` |
253
+ |---|---|
254
+ | `401` from most commands | Run `af doctor --json` — then `af login` to refresh |
255
+ | `404: <Resource> not found` | Run the matching `list` command to see real IDs (error `hint` points you there) |
256
+ | `422` with pydantic errors | Inspect `details.payload` — field-level errors are there |
257
+ | `af agent update` 422s on null fields | Use `--patch` (auto-strips null-rejected fields) |
258
+ | `af workforce run` 400 "Failed to retrieve user info" | Known backend issue for API-key auth — not a CLI bug |
259
+ | `af paperclip *` deprecation noise | Set `AF_SILENCE_DEPRECATIONS=1` while migrating; use `af playbook migrate-from-paperclip` |
260
+ | Node TLS warning | CLI now unsets inherited `NODE_TLS_REJECT_UNAUTHORIZED=0`; set `AF_INSECURE_TLS=1` if you genuinely need it |
261
+ | Connections list too short | Default limit is 10; use `--limit 200` |
233
262
 
234
263
  ## Links
235
264
 
package/dist/cli/changelog.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"changelog.d.ts","sourceRoot":"","sources":["../../src/cli/changelog.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,eAAO,MAAM,SAAS,EAAE,cAAc,EAqLrC,CAAC;AAEF,wBAAgB,kBAAkB,IAAI,cAAc,CAEnD;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,EAAE,CAInE"}
1
+ {"version":3,"file":"changelog.d.ts","sourceRoot":"","sources":["../../src/cli/changelog.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,eAAO,MAAM,SAAS,EAAE,cAAc,EAkNrC,CAAC;AAEF,wBAAgB,kBAAkB,IAAI,cAAc,CAEnD;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,EAAE,CAInE"}
package/dist/cli/changelog.js CHANGED
@@ -5,6 +5,35 @@
5
5
  * and displayed after upgrade.
6
6
  */
7
7
  export const CHANGELOG = [
8
+ {
9
+ version: "1.6.3",
10
+ date: "2026-04-14",
11
+ highlights: [
12
+ "`af schema agent --field suggested_messages` now shows the real shape: `array of { title, label, action }` (object, not strings). Previously the CLI doc said 'array of strings' and the server 422'd — verified against the AgenticFlow `AgentSuggestedMessage` pydantic model in workflow_chef",
13
+ "New agent-vs-workforce decision table added to README (top-of-page) + CONTEXT.md + `af context` invariants. A single customer-facing bot should be `af agent create` with rules in the system prompt — not a `support-center` workforce",
14
+ "`af playbook first-touch` STEP 2 fixed: no longer references `af paperclip blueprints` (was a stale leak from the v1.6.1 playbook pass). Points at `af bootstrap > blueprints[]` instead",
15
+ ],
16
+ for_ai: [
17
+ "If you need `suggested_messages` on an agent, each item is `{title: string, label: string, action: string}` — `title` shows as the button text, `action` is the message sent on click",
18
+ "DECISION HEURISTIC: one chat endpoint → `af agent create`. Multiple agents with hand-off → `af workforce init --blueprint <id>`. When in doubt, start with agent — you can always graduate to a workforce later",
19
+ "`af context --json` invariants now include the agent-vs-workforce choice explicitly — it used to over-rotate operators toward workforce",
20
+ ],
21
+ },
22
+ {
23
+ version: "1.6.2",
24
+ date: "2026-04-14",
25
+ highlights: [
26
+ "README.md rewritten for v1.6 — leads with `af workforce init`, documents `--patch`, `af mcp-clients inspect`, schema `--field` drilldown, new env vars (AF_SILENCE_DEPRECATIONS, AF_INSECURE_TLS), and marks paperclip surface deprecated with sunset 2026-10-14. Synced to the `README.md` shown on npm",
27
+ "CONTEXT.md rewritten for AI-agent operators — new 'The journey' section walks from orient → learn → shape → preview → build → test → iterate → ship → cleanup",
28
+ "`af context --json` updated: invariants now surface --patch preference, MCP inspect-before-attach, and hint/details.payload recovery pattern. New `journey` + `bootstrap_sequence` arrays replace the old `af doctor` lead",
29
+ "Env-var inventory in context now includes AF_SILENCE_DEPRECATIONS and AF_INSECURE_TLS",
30
+ ],
31
+ for_ai: [
32
+ "If your onboarding stalls on Paperclip docs, pull the latest README — v1.6.2 leads with `af workforce init`, paperclip is clearly demoted with a 2026-10-14 sunset",
33
+ "`af context --json` now returns a `journey` array with the 9-step build→ship flow the CLI is designed to support",
34
+ "The invariants list is updated — start with `af bootstrap --json` (not `af doctor`), prefer `--patch` for iteration, inspect MCPs before attach",
35
+ ],
36
+ },
8
37
  {
9
38
  version: "1.6.1",
10
39
  date: "2026-04-14",
package/dist/cli/changelog.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"changelog.js","sourceRoot":"","sources":["../../src/cli/changelog.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"changelog.js","sourceRoot":"","sources":["../../src/cli/changelog.ts"],"names":[],"mappings":"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"}
package/dist/cli/main.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAi8BpC,wBAAgB,aAAa,IAAI,OAAO,CAu/KvC;AAED,wBAAsB,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAwB3D"}
1
+ {"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAi8BpC,wBAAgB,aAAa,IAAI,OAAO,CA4gLvC;AAED,wBAAsB,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAwB3D"}
package/dist/cli/main.js CHANGED
@@ -830,7 +830,7 @@ export function createProgram() {
830
830
  suggest_replies: "bool (default: true) — generate suggested follow-up replies",
831
831
  auto_generate_title: "bool (default: true) — auto-title new threads",
832
832
  welcome_message: "string — greeting on new thread",
833
- suggested_messages: "array of strings — pre-populated example prompts shown to users",
833
+ suggested_messages: "array of { title: string, label: string, action: string } — pre-populated example prompts shown to users. `title` is the short display text; `label` is the sub-text; `action` is the message body sent on click. NOT an array of strings — server rejects strings",
834
834
  sub_agents: "array — sub-agent configurations for agent teams",
835
835
  plugins: "array — plugin configurations",
836
836
  },
@@ -1061,23 +1061,41 @@ export function createProgram() {
1061
1061
  printResult({
1062
1062
  schema: "agenticflow.context.v1",
1063
1063
  invariants: [
1064
- "ALWAYS use --json for machine-readable output",
1065
- "ALWAYS run `af doctor --json --strict` at session start",
1066
- "ALWAYS use `af schema <resource>` before constructing payloads",
1067
- "ALWAYS use --dry-run before mutating operations",
1068
- "ALWAYS use --fields on list commands to save context window",
1064
+ "ALWAYS run `af bootstrap --json` first — it returns everything (auth, agents, workforces, blueprints, playbooks, what's new) in one call",
1065
+ "ALWAYS use --json for machine-readable output in automation",
1066
+ "ALWAYS use --dry-run before mutating create/deploy commands you're not 100% sure about",
1067
+ "ALWAYS use --fields on list commands (saves context window)",
1068
+ "CHOOSE agent vs workforce by orchestration need: single chat endpoint / one assistant → `af agent create`. Multiple agents with hand-off (research → write, triage → specialist, the 6 built-in blueprints) → `af workforce init --blueprint <id>`. Don't use a workforce for single-bot use cases",
1069
+ "PREFER `af agent update --patch` over full-body PUT — preserves MCP clients + tools + code_exec while changing only the fields you supply",
1070
+ "PREFER `af workforce init --blueprint <id>` over wiring a workforce's agents manually — one command creates workforce + agents + wired DAG (v1.6+)",
1071
+ "USE `af schema <resource> --field <name>` to drill into nested payload shapes (e.g. mcp_clients, suggested_messages, response_format) instead of guessing",
1072
+ "BEFORE attaching an MCP client, run `af mcp-clients inspect --id <id>` — pattern=pipedream with write_capable_tools is likely to fail on execute. See `af playbook mcp-client-quirks`",
1073
+ "ON errors, check `hint` and `details.payload` — the CLI tells you exactly what to fix before you retry",
1069
1074
  "NEVER hard-code IDs — fetch dynamically via list/get",
1070
1075
  ],
1071
1076
  bootstrap_sequence: [
1072
- "af context --json",
1073
- "af doctor --json --strict",
1074
- "af schema --json",
1075
- "af agent list --fields id,name,model --json",
1077
+ "af bootstrap --json # single-call orientation (auth + agents + workforces + blueprints + playbooks + whats_new)",
1078
+ "af playbook first-touch # read the canonical onboarding walkthrough",
1079
+ "af schema <resource> --json # inspect payload shape for the resource you're about to touch",
1080
+ ],
1081
+ journey: [
1082
+ "1. Orient: af bootstrap --json",
1083
+ "2. Learn: af playbook <topic> (migrate-from-paperclip, mcp-client-quirks, amazon-seller, …)",
1084
+ "3. Shape: af schema <resource> [--field <name>]",
1085
+ "4. Preview: af <resource> create --body @file --dry-run --json",
1086
+ "5. Build: af <resource> create --body @file --json (or workforce init --blueprint <id>)",
1087
+ "6. Test: af agent run --agent-id <id> --message '...' --json",
1088
+ "7. Iterate: af agent update --agent-id <id> --patch --body '{\"field\":\"new\"}'",
1089
+ "8. Ship: af workforce publish --workforce-id <id> (public URL)",
1090
+ "9. Cleanup: af <resource> delete --<resource>-id <id> --json",
1076
1091
  ],
1077
1092
  discovery: {
1093
+ bootstrap: "af bootstrap --json",
1078
1094
  schemas: "af schema --json",
1095
+ schema_field: "af schema <resource> --field <name> --json",
1079
1096
  capabilities: "af discover --json",
1080
1097
  playbooks: "af playbook --list --json",
1098
+ changelog: "af changelog --json",
1081
1099
  gateway_channels: "af gateway channels --json",
1082
1100
  },
1083
1101
  resources: Object.keys(SCHEMAS),
@@ -1085,13 +1103,16 @@ export function createProgram() {
1085
1103
  AGENTICFLOW_API_KEY: "API key (required)",
1086
1104
  AGENTICFLOW_WORKSPACE_ID: "Default workspace",
1087
1105
  AGENTICFLOW_PROJECT_ID: "Default project",
1088
- PAPERCLIP_URL: "Paperclip instance URL",
1089
- LINEAR_API_KEY: "Linear API key",
1106
+ AF_SILENCE_DEPRECATIONS: "Set =1 to suppress `af paperclip` deprecation warnings while migrating",
1107
+ AF_INSECURE_TLS: "Set =1 to opt-in to insecure TLS for self-signed dev backends (off by default)",
1108
+ PAPERCLIP_URL: "Paperclip URL — deprecated, sunset 2026-10-14",
1109
+ LINEAR_API_KEY: "Linear API key (for gateway)",
1090
1110
  },
1091
1111
  global_flags: {
1092
- "--json": "Machine-readable JSON output",
1112
+ "--json": "Machine-readable JSON output with `schema:` discriminator",
1093
1113
  "--fields <f>": "Comma-separated fields to return (saves tokens)",
1094
- "--dry-run": "Validate without executing (on create commands)",
1114
+ "--dry-run": "Validate without executing (on create/deploy commands)",
1115
+ "--patch": "Partial update: fetch → merge → PUT (on `af agent update` and other update commands)",
1095
1116
  },
1096
1117
  });
1097
1118
  }