@pixelml/agenticflow-cli 1.6.0 → 1.6.2

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 +149 -124
  2. package/dist/cli/changelog.d.ts.map +1 -1
  3. package/dist/cli/changelog.js +30 -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 +33 -13
  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 +122 -67
  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,210 @@ 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
+ - **Single agents** — `af agent create/run/update/delete`, with `--patch` for surgical iteration
36
+ - **Multi-agent workforces** — `af workforce init --blueprint <id>` deploys a runnable DAG (trigger → coordinator → workers → output) with real agents auto-created and wired up
37
+ - **Workflows** — `af workflow create/run/run-status` for DAG-style workflow automation
38
+ - **MCP tool integrations** — `af mcp-clients list/inspect` to audit + attach Google Docs/Sheets, Notion, Slack, GitHub, etc.
32
39
 
33
40
  ## Authentication
34
41
 
35
42
  | 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 |
43
+ |---|---|---|
44
+ | Interactive login | `af login` | First-time setup |
45
+ | Environment variable | `export AGENTICFLOW_API_KEY=<key>` | CI/CD, automated agents |
46
+ | CLI flag | `--api-key <key>` | One-off scripts |
47
+ | Import from `.env` | `af auth import-env --file .env` | Batch import |
41
48
 
42
49
  ```bash
43
- af login # Interactive setup (saves to ~/.agenticflow/auth.json)
50
+ af login # Saves to ~/.agenticflow/auth.json
44
51
  af whoami --json
45
- af doctor --json --strict
52
+ af doctor --json --strict # Preflight with explicit exit codes
46
53
  ```
47
54
 
48
55
  ### Environment Variables
49
56
 
50
57
  | Variable | Purpose |
51
- |----------|---------|
58
+ |---|---|
52
59
  | `AGENTICFLOW_API_KEY` | API key |
53
60
  | `AGENTICFLOW_WORKSPACE_ID` | Default workspace ID |
54
61
  | `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) |
62
+ | `AF_SILENCE_DEPRECATIONS=1` | Suppress `af paperclip` deprecation warnings while migrating |
63
+ | `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`) |
64
+ | `PAPERCLIP_URL` | Paperclip URL (deprecated — sunset 2026-10-14) |
65
+ | `LINEAR_API_KEY` / `LINEAR_AGENT_MAP` | Linear gateway config |
59
66
 
60
- ## Commands
61
-
62
- ### AI-Agent Discovery
67
+ ## AI-Agent Discovery
63
68
 
64
69
  ```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
70
+ af bootstrap --json # THE one-shot orientation — start here
71
+ af context --json # AI-agent usage guide (invariants, schemas)
72
+ af schema # List all resource schemas
73
+ af schema agent # Agent create/update/stream shape
74
+ af schema agent --field mcp_clients # Drill into a specific field (v1.5.1+)
75
+ af schema workforce --field schema # Workforce graph shape (nodes + edges)
76
+ af playbook # List all guided playbooks
77
+ af playbook first-touch # Zero-to-working-agent walkthrough
78
+ af changelog --json # What changed after an upgrade
71
79
  ```
72
80
 
81
+ ## Core Commands
82
+
73
83
  ### Agents
74
84
 
75
85
  ```bash
76
- af agent list --fields id,name,model --json # List (with field filter)
86
+ af agent list --fields id,name,model --json
87
+ af agent list --name-contains silk --fields id,name --json # v1.5.1+ client-side filter
77
88
  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
89
+ af agent create --body @agent.json --dry-run --json # Validate first
90
+ af agent create --body @agent.json --json
91
+ af agent update --agent-id <id> --patch --body '{"system_prompt":"..."}' # v1.5.0+ partial update (fetch → merge → PUT)
92
+ af agent delete --agent-id <id> --json
93
+ af agent run --agent-id <id> --message "..." --json # Non-streaming (returns {response, thread_id})
94
+ af agent run --agent-id <id> --thread-id <tid> --message "continue..."
95
+ af agent stream --agent-id <id> --body @messages.json # SSE streaming
83
96
  ```
84
97
 
85
- ### Workflows
98
+ `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.
99
+
100
+ ### Workforces (v1.5.0+) — the native multi-agent deploy
86
101
 
87
102
  ```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
103
+ af workforce init --blueprint <slug> --name "My Team" --dry-run --json # Preview
104
+ af workforce init --blueprint <slug> --name "My Team" --json # Create workforce + agents + wired DAG, atomic rollback on failure
105
+
106
+ af workforce list --fields id,name --json
107
+ af workforce schema --workforce-id <id> --json # Full graph (nodes + edges)
108
+ af workforce deploy --workforce-id <id> --body @graph.json --json # Atomic graph replace
109
+ af workforce validate --workforce-id <id> --json # Cycle detection
110
+ af workforce run --workforce-id <id> --trigger-data '{"message":"..."}' # SSE stream
111
+ af workforce versions list --workforce-id <id> --json
112
+ af workforce versions publish --workforce-id <id> --version-id <v>
113
+ af workforce publish --workforce-id <id> --json # Public key + URL
114
+ af workforce delete --workforce-id <id> --json
95
115
  ```
96
116
 
97
- ### Webhook Gateway
117
+ 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
118
 
99
- Receive tasks from any platform and route them to AgenticFlow agents:
119
+ ### MCP Clients
100
120
 
101
121
  ```bash
102
- # Start the gateway
103
- af gateway serve --channels paperclip,linear,webhook --verbose
104
-
105
- # Available channels
106
- af gateway channels
122
+ af mcp-clients list --name-contains "google sheets" --fields id,name --json # v1.5.2+
123
+ af mcp-clients list --verify-auth --json # Reconcile stale auth flags
124
+ af mcp-clients get --id <id> --json # `--client-id` also works
125
+ af mcp-clients inspect --id <id> --json # v1.5.1+ — classify Pipedream vs Composio, flag write quirks
107
126
  ```
108
127
 
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
- ```
128
+ See `af playbook mcp-client-quirks` — some MCP providers break on parametric writes. Inspect before attaching.
115
129
 
116
- **Paperclip channel** — receive heartbeats from a Paperclip company:
117
- ```bash
118
- af gateway serve --channels paperclip --paperclip-url http://localhost:3100
119
- ```
130
+ ### Workflows
120
131
 
121
- **Linear channel** — process Linear issues:
122
132
  ```bash
123
- export LINEAR_API_KEY=lin_api_xxxxx
124
- export LINEAR_AGENT_MAP='{"ENG":"<af-agent-id>"}'
125
- af gateway serve --channels linear
133
+ af workflow list --fields id,name,status --json
134
+ af workflow get --workflow-id <id> --json
135
+ af workflow validate --body @wf.json --local-only
136
+ af workflow create --body @wf.json --json
137
+ af workflow run --workflow-id <id> --input @input.json
138
+ af workflow run-status --workflow-run-id <run_id> --json
126
139
  ```
127
140
 
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:
141
+ ### Company (portable agent-bundle export/import)
133
142
 
134
143
  ```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
144
+ af company export --output company-export.yaml
145
+ af company diff company-export.yaml --json # Phase 7 — field-level diff
146
+ af company import --merge company-export.yaml --conflict-strategy local
147
+ ```
141
148
 
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
149
+ ### Paperclip (DEPRECATED — sunset 2026-10-14)
145
150
 
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>
151
+ `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
152
 
151
- # Monitor
152
- af paperclip dashboard
153
- af paperclip issue comments --id <issue-id>
154
- ```
153
+ ### Webhook Gateway
155
154
 
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
155
+ ```bash
156
+ af gateway serve --channels webhook,linear --verbose
157
+ af gateway channels
166
158
  ```
167
159
 
168
- ### Node Types
169
-
160
+ Send a task:
170
161
  ```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)
162
+ curl -X POST http://localhost:4100/webhook/webhook \
163
+ -H "Content-Type: application/json" \
164
+ -d '{"agent_id":"<id>","message":"Do X","callback_url":"https://..."}'
174
165
  ```
175
166
 
176
- ### Connections
167
+ ### Node Types & Connections
177
168
 
178
169
  ```bash
170
+ af node-types search --query "llm" --json
171
+ af node-types get --name <type> --json
179
172
  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
173
  ```
184
174
 
185
- ### Playbooks
175
+ ## Playbooks — guided paths
186
176
 
187
177
  ```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
178
+ af playbook first-touch # AI-agent onboarding (START HERE)
179
+ af playbook quickstart # Zero → working agent in 5 minutes
180
+ af playbook agent-build # Agent configuration deep dive
181
+ af playbook workflow-build # Workflow design checklist
182
+ af playbook workflow-run # Execute + monitor workflows
183
+ af playbook amazon-seller # Full Amazon SG seller team deploy
184
+ af playbook company-from-scratch # Build an AI company step-by-step
185
+ af playbook migrate-from-paperclip # Paperclip → workforce command map (v1.5.0+)
186
+ af playbook mcp-client-quirks # Pipedream vs Composio — attach safety (v1.5.1+)
187
+ af playbook gateway-setup # Multi-channel webhook gateway
188
+ af playbook agent-channels # Connect Linear, webhooks, etc.
189
+ af playbook template-bootstrap # Start from pre-built templates
190
+ af playbook mcp-to-cli-map # MCP → CLI command mapping
191
+ af playbook deploy-to-paperclip # [DEPRECATED] legacy Paperclip deploy
196
192
  ```
197
193
 
198
194
  ## Global Options
199
195
 
200
196
  | Flag | Purpose |
201
- |------|---------|
202
- | `--json` | Machine-readable JSON output |
197
+ |---|---|
198
+ | `--json` | Machine-readable JSON output with `schema:` discriminators |
203
199
  | `--fields <fields>` | Filter output fields (saves context window) |
204
- | `--dry-run` | Validate without executing (on create commands) |
200
+ | `--dry-run` | Validate without executing (on create/deploy commands) |
201
+ | `--patch` | Partial update (on `af agent update` and other update commands) |
205
202
  | `--api-key <key>` | Override API key |
206
203
  | `--workspace-id <id>` | Override workspace |
207
204
  | `--project-id <id>` | Override project |
208
205
 
206
+ ## Error handling
207
+
208
+ Every `--json` error returns a consistent envelope:
209
+
210
+ ```json
211
+ {
212
+ "schema": "agenticflow.error.v1",
213
+ "code": "request_failed",
214
+ "message": "Request failed with status 404: Agent not found",
215
+ "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.",
216
+ "details": {
217
+ "status_code": 404,
218
+ "payload": { "detail": "Agent not found" }
219
+ }
220
+ }
221
+ ```
222
+
223
+ Common codes: `local_schema_validation_failed`, `request_failed`, `operation_not_found`, `invalid_option_value`, `missing_required_option`, `workforce_init_failed`.
224
+
209
225
  ## SDK
210
226
 
211
227
  ```typescript
@@ -217,19 +233,28 @@ const client = createClient({
217
233
  projectId: process.env.AGENTICFLOW_PROJECT_ID,
218
234
  });
219
235
 
236
+ // Agents
220
237
  const agents = await client.agents.list();
221
- const result = await client.workflows.run("workflow-id", { query: "hello" });
238
+ await client.agents.patch(agentId, { system_prompt: "..." });
239
+
240
+ // Workforces (v1.5.0+)
241
+ const wf = await client.workforces.create({ name: "My Team" });
242
+ await client.workforces.putSchema(wf.id, { nodes, edges });
243
+ const stream = await client.workforces.run(wf.id, { trigger_data: { message: "..." } });
222
244
  ```
223
245
 
224
246
  ## Troubleshooting
225
247
 
226
248
  | 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` |
249
+ |---|---|
250
+ | `401` from most commands | Run `af doctor --json` — then `af login` to refresh |
251
+ | `404: <Resource> not found` | Run the matching `list` command to see real IDs (error `hint` points you there) |
252
+ | `422` with pydantic errors | Inspect `details.payload` — field-level errors are there |
253
+ | `af agent update` 422s on null fields | Use `--patch` (auto-strips null-rejected fields) |
254
+ | `af workforce run` 400 "Failed to retrieve user info" | Known backend issue for API-key auth — not a CLI bug |
255
+ | `af paperclip *` deprecation noise | Set `AF_SILENCE_DEPRECATIONS=1` while migrating; use `af playbook migrate-from-paperclip` |
256
+ | Node TLS warning | CLI now unsets inherited `NODE_TLS_REJECT_UNAUTHORIZED=0`; set `AF_INSECURE_TLS=1` if you genuinely need it |
257
+ | Connections list too short | Default limit is 10; use `--limit 200` |
233
258
 
234
259
  ## Links
235
260
 
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,EAsKrC,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,EAoMrC,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,36 @@
5
5
  * and displayed after upgrade.
6
6
  */
7
7
  export const CHANGELOG = [
8
+ {
9
+ version: "1.6.2",
10
+ date: "2026-04-14",
11
+ highlights: [
12
+ "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",
13
+ "CONTEXT.md rewritten for AI-agent operators — new 'The journey' section walks from orient → learn → shape → preview → build → test → iterate → ship → cleanup",
14
+ "`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",
15
+ "Env-var inventory in context now includes AF_SILENCE_DEPRECATIONS and AF_INSECURE_TLS",
16
+ ],
17
+ for_ai: [
18
+ "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",
19
+ "`af context --json` now returns a `journey` array with the 9-step build→ship flow the CLI is designed to support",
20
+ "The invariants list is updated — start with `af bootstrap --json` (not `af doctor`), prefer `--patch` for iteration, inspect MCPs before attach",
21
+ ],
22
+ },
23
+ {
24
+ version: "1.6.1",
25
+ date: "2026-04-14",
26
+ highlights: [
27
+ "Playbook freshness pass — three onboarding playbooks (`first-touch`, `amazon-seller`, `company-from-scratch`) now lead with `af workforce init` (v1.6 native deploy) and show the deprecated `af paperclip init` path as a secondary option with a sunset date",
28
+ "`deploy-to-paperclip` playbook got a prominent `⚠️ DEPRECATED` header pointing at `af playbook migrate-from-paperclip` and the sunset 2026-10-14",
29
+ "`amazon-seller` playbook expanded: shows `--include-optional-slots` to create all 5 agents, attach-MCP-per-agent recipe pointing at `mcp-client-quirks`, and smoke-run/publish commands",
30
+ "Verified: all 6 blueprints translate cleanly through `--dry-run` (node/edge math correct). Full e2e `content-studio` deploy creates + wires + validates + tears down cleanly",
31
+ ],
32
+ for_ai: [
33
+ "When `af bootstrap --json` returns workforces=0 and the user wants a team, the FIRST thing to show them is `af workforce init --blueprint <id> --dry-run --json` — the playbooks now lead with this, no longer with paperclip",
34
+ "For Amazon Singapore sellers, run `af playbook amazon-seller` — it shows the one-command native deploy path first, with `--include-optional-slots` for the full 5-agent team",
35
+ "`af playbook deploy-to-paperclip` now explicitly flags itself deprecated and points at `migrate-from-paperclip` — follow that path unless the user has an existing Paperclip instance",
36
+ ],
37
+ },
8
38
  {
9
39
  version: "1.6.0",
10
40
  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,CA2gLvC;AAED,wBAAsB,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAwB3D"}
package/dist/cli/main.js CHANGED
@@ -1061,23 +1061,40 @@ 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
+ "PREFER `af agent update --patch` over full-body PUT — preserves MCP clients + tools + code_exec while changing only the fields you supply",
1069
+ "PREFER `af workforce init --blueprint <id>` over wiring agents manually — one command = runnable team (v1.6+)",
1070
+ "USE `af schema <resource> --field <name>` to drill into nested payload shapes (e.g. mcp_clients, response_format) instead of guessing",
1071
+ "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`",
1072
+ "ON errors, check `hint` and `details.payload` — the CLI tells you exactly what to fix before you retry",
1069
1073
  "NEVER hard-code IDs — fetch dynamically via list/get",
1070
1074
  ],
1071
1075
  bootstrap_sequence: [
1072
- "af context --json",
1073
- "af doctor --json --strict",
1074
- "af schema --json",
1075
- "af agent list --fields id,name,model --json",
1076
+ "af bootstrap --json # single-call orientation (auth + agents + workforces + blueprints + playbooks + whats_new)",
1077
+ "af playbook first-touch # read the canonical onboarding walkthrough",
1078
+ "af schema <resource> --json # inspect payload shape for the resource you're about to touch",
1079
+ ],
1080
+ journey: [
1081
+ "1. Orient: af bootstrap --json",
1082
+ "2. Learn: af playbook <topic> (migrate-from-paperclip, mcp-client-quirks, amazon-seller, …)",
1083
+ "3. Shape: af schema <resource> [--field <name>]",
1084
+ "4. Preview: af <resource> create --body @file --dry-run --json",
1085
+ "5. Build: af <resource> create --body @file --json (or workforce init --blueprint <id>)",
1086
+ "6. Test: af agent run --agent-id <id> --message '...' --json",
1087
+ "7. Iterate: af agent update --agent-id <id> --patch --body '{\"field\":\"new\"}'",
1088
+ "8. Ship: af workforce publish --workforce-id <id> (public URL)",
1089
+ "9. Cleanup: af <resource> delete --<resource>-id <id> --json",
1076
1090
  ],
1077
1091
  discovery: {
1092
+ bootstrap: "af bootstrap --json",
1078
1093
  schemas: "af schema --json",
1094
+ schema_field: "af schema <resource> --field <name> --json",
1079
1095
  capabilities: "af discover --json",
1080
1096
  playbooks: "af playbook --list --json",
1097
+ changelog: "af changelog --json",
1081
1098
  gateway_channels: "af gateway channels --json",
1082
1099
  },
1083
1100
  resources: Object.keys(SCHEMAS),
@@ -1085,13 +1102,16 @@ export function createProgram() {
1085
1102
  AGENTICFLOW_API_KEY: "API key (required)",
1086
1103
  AGENTICFLOW_WORKSPACE_ID: "Default workspace",
1087
1104
  AGENTICFLOW_PROJECT_ID: "Default project",
1088
- PAPERCLIP_URL: "Paperclip instance URL",
1089
- LINEAR_API_KEY: "Linear API key",
1105
+ AF_SILENCE_DEPRECATIONS: "Set =1 to suppress `af paperclip` deprecation warnings while migrating",
1106
+ AF_INSECURE_TLS: "Set =1 to opt-in to insecure TLS for self-signed dev backends (off by default)",
1107
+ PAPERCLIP_URL: "Paperclip URL — deprecated, sunset 2026-10-14",
1108
+ LINEAR_API_KEY: "Linear API key (for gateway)",
1090
1109
  },
1091
1110
  global_flags: {
1092
- "--json": "Machine-readable JSON output",
1111
+ "--json": "Machine-readable JSON output with `schema:` discriminator",
1093
1112
  "--fields <f>": "Comma-separated fields to return (saves tokens)",
1094
- "--dry-run": "Validate without executing (on create commands)",
1113
+ "--dry-run": "Validate without executing (on create/deploy commands)",
1114
+ "--patch": "Partial update: fetch → merge → PUT (on `af agent update` and other update commands)",
1095
1115
  },
1096
1116
  });
1097
1117
  }