@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.
- package/README.md +153 -124
- package/dist/cli/changelog.d.ts.map +1 -1
- package/dist/cli/changelog.js +29 -0
- package/dist/cli/changelog.js.map +1 -1
- package/dist/cli/main.d.ts.map +1 -1
- package/dist/cli/main.js +35 -14
- package/dist/cli/main.js.map +1 -1
- package/dist/cli/playbooks.d.ts.map +1 -1
- package/dist/cli/playbooks.js +11 -1
- package/dist/cli/playbooks.js.map +1 -1
- 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
|
|
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
|
[](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.
|
|
22
|
-
af
|
|
21
|
+
# 2. One-shot orientation — auth, agents, workforces, blueprints, playbooks, what's new
|
|
22
|
+
af bootstrap --json
|
|
23
23
|
|
|
24
|
-
# 3.
|
|
25
|
-
af agent
|
|
24
|
+
# 3. Talk to an existing agent
|
|
25
|
+
af agent run --agent-id <id> --message "Hello!" --json
|
|
26
26
|
|
|
27
|
-
# 4.
|
|
28
|
-
af
|
|
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**:
|
|
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
|
-
|
|
|
38
|
-
|
|
|
39
|
-
|
|
|
40
|
-
|
|
|
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
|
|
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
|
-
| `
|
|
56
|
-
| `
|
|
57
|
-
| `
|
|
58
|
-
| `LINEAR_AGENT_MAP` |
|
|
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
|
-
|
|
71
|
+
## AI-Agent Discovery
|
|
63
72
|
|
|
64
73
|
```bash
|
|
65
|
-
af
|
|
66
|
-
af
|
|
67
|
-
af schema
|
|
68
|
-
af schema
|
|
69
|
-
af
|
|
70
|
-
af
|
|
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
|
|
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
|
|
79
|
-
af agent create --body @agent.json
|
|
80
|
-
af agent update --agent-id <id> --body
|
|
81
|
-
af agent delete --agent-id <id>
|
|
82
|
-
af agent
|
|
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
|
-
|
|
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
|
|
89
|
-
af
|
|
90
|
-
|
|
91
|
-
af
|
|
92
|
-
af
|
|
93
|
-
af
|
|
94
|
-
af
|
|
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
|
-
|
|
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
|
-
|
|
123
|
+
### MCP Clients
|
|
100
124
|
|
|
101
125
|
```bash
|
|
102
|
-
|
|
103
|
-
af
|
|
104
|
-
|
|
105
|
-
#
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
124
|
-
|
|
125
|
-
af
|
|
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
|
-
|
|
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
|
-
|
|
136
|
-
af
|
|
137
|
-
|
|
138
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
152
|
-
af paperclip dashboard
|
|
153
|
-
af paperclip issue comments --id <issue-id>
|
|
154
|
-
```
|
|
157
|
+
### Webhook Gateway
|
|
155
158
|
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
af
|
|
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
|
-
|
|
169
|
-
|
|
164
|
+
Send a task:
|
|
170
165
|
```bash
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
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
|
-
|
|
179
|
+
## Playbooks — guided paths
|
|
186
180
|
|
|
187
181
|
```bash
|
|
188
|
-
af playbook
|
|
189
|
-
af playbook
|
|
190
|
-
af playbook
|
|
191
|
-
af playbook
|
|
192
|
-
af playbook
|
|
193
|
-
af playbook
|
|
194
|
-
af playbook
|
|
195
|
-
af playbook
|
|
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
|
-
|
|
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
|
-
| `
|
|
229
|
-
| `
|
|
230
|
-
| `
|
|
231
|
-
| `
|
|
232
|
-
|
|
|
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
|
|
|
@@ -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,
|
|
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",
|
|
@@ -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,
|
|
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
|
|
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
|
|
1065
|
-
"ALWAYS
|
|
1066
|
-
"ALWAYS use
|
|
1067
|
-
"ALWAYS use --
|
|
1068
|
-
"
|
|
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
|
|
1073
|
-
"af
|
|
1074
|
-
"af schema --json",
|
|
1075
|
-
|
|
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
|
-
|
|
1089
|
-
|
|
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
|
}
|