@roilab/crm-cli 0.12.0 → 0.15.0
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/CHANGELOG.md +60 -1
- package/SKILL.md +622 -587
- package/SURFACE.txt +42 -5
- package/dist/bin/crm.js +4 -0
- package/dist/bin/crm.js.map +1 -1
- package/dist/src/commands/board.js +22 -0
- package/dist/src/commands/board.js.map +1 -0
- package/dist/src/commands/doc.js +267 -0
- package/dist/src/commands/doc.js.map +1 -0
- package/dist/src/commands/generic.js +60 -0
- package/dist/src/commands/generic.js.map +1 -1
- package/dist/src/commands/integrations.js +185 -0
- package/dist/src/commands/integrations.js.map +1 -1
- package/dist/src/commands/task.js +6 -0
- package/dist/src/commands/task.js.map +1 -1
- package/package.json +58 -58
- package/skill-bundles/tools/task-preflight/SKILL.md +8 -0
- package/skill-bundles/tools/tool-routing/SKILL.md +60 -60
package/SKILL.md
CHANGED
|
@@ -1,587 +1,622 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: crm
|
|
3
|
-
description: Drive the ROILab SEO+CRM from a shell. Tasks, comments, file attachments, chat threads, analytics, backlinks, change events, and cross-entity recall — every action is auditable and attributed to you as an agent.
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# `crm` — CLI for AI agents + humans
|
|
7
|
-
|
|
8
|
-
This skill teaches you to operate the ROILab SEO+CRM via the `crm` binary. All writes you make are stamped `actorType: "agent"` and associated with your API key, so there is a robot badge next to your changes in the web UI. Humans can filter and review what you did.
|
|
9
|
-
|
|
10
|
-
## Capabilities you might miss (flags, not verbs)
|
|
11
|
-
|
|
12
|
-
Some features ship as **flags on existing commands**, not as new subcommands —
|
|
13
|
-
if you only list verbs (`crm task --help`) you won't see them. Look for these:
|
|
14
|
-
|
|
15
|
-
| Flag | Where | What it does |
|
|
16
|
-
|---|---|---|
|
|
17
|
-
| `--file <path...>` | `crm task create` / `task update` / `comment create` / `chat send` / `chat reply` | Adjunta archivo(s) en la misma escritura. Repetible. Máx 10 MB; aviso desde 2 MB. Detalles en "Adjuntar archivos" más abajo. |
|
|
18
|
-
| `--shadow` | cualquier write | Fuerza propuesta pendiente de revisión humana. |
|
|
19
|
-
| `--wait-for-approval --timeout 30m` | cualquier write con shadow | Bloquea hasta que un humano decida. |
|
|
20
|
-
| `--idempotency-key <key>` | cualquier write | Reintentos seguros entre invocaciones. |
|
|
21
|
-
| `--ids-only` / `--quiet` / `--count` / `--markdown` / `--jq <expr>` | cualquier comando | Modos de salida (mutuamente excluyentes salvo `--jq`). |
|
|
22
|
-
|
|
23
|
-
Si dudas si una capacidad existe, **revisa los flags de cada verbo**
|
|
24
|
-
(`crm <noun> <verb> --help`), no sólo la lista de verbos. También puedes
|
|
25
|
-
grepear `cli/SURFACE.txt` (envoltura plana de la superficie).
|
|
26
|
-
|
|
27
|
-
## Getting started
|
|
28
|
-
|
|
29
|
-
Two ways to authenticate, pick the one that matches your environment.
|
|
30
|
-
|
|
31
|
-
**Device flow — for human-driven use (recommended):**
|
|
32
|
-
|
|
33
|
-
```bash
|
|
34
|
-
crm auth login --api-url https://crm.roilab.es
|
|
35
|
-
# Prints a URL + 8-char code. Open the URL in your already-signed-in
|
|
36
|
-
# browser and click "Approve". The CLI polls and stores a 1-hour access
|
|
37
|
-
# token + 30-day refresh token. Tokens auto-rotate; nothing long-lived
|
|
38
|
-
# ends up on disk.
|
|
39
|
-
```
|
|
40
|
-
|
|
41
|
-
**API key — for unattended use (CI, agents-as-a-service):**
|
|
42
|
-
|
|
43
|
-
```bash
|
|
44
|
-
export CRM_API_KEY=crm_ak_... # or crm auth login crm_ak_...
|
|
45
|
-
crm doctor # verify reachability + auth
|
|
46
|
-
crm task list --status todo --limit 5
|
|
47
|
-
```
|
|
48
|
-
|
|
49
|
-
API keys are long-lived and workspace-scoped; leak-sensitive. Prefer the
|
|
50
|
-
device flow for interactive use; use raw keys only where a browser isn't
|
|
51
|
-
available.
|
|
52
|
-
|
|
53
|
-
If you need a new API key, ask the human to visit `Settings → Developers
|
|
54
|
-
→ API Keys` in the web UI and share one.
|
|
55
|
-
|
|
56
|
-
## Output contract — read this carefully
|
|
57
|
-
|
|
58
|
-
Every command emits a JSON envelope. Use `--jq` for filtering, **never pipe to `jq`**:
|
|
59
|
-
|
|
60
|
-
```bash
|
|
61
|
-
crm task list --jq '.data[].title' # OK
|
|
62
|
-
crm task list | jq '.data[].title' # WRONG — the envelope matters
|
|
63
|
-
```
|
|
64
|
-
|
|
65
|
-
Flags (mutually exclusive except `--jq`):
|
|
66
|
-
- `--json` — default. Full envelope with `ok`, `data`, `summary`, `breadcrumbs`, `meta`.
|
|
67
|
-
- `--quiet` — just `data`. Good for pipelines.
|
|
68
|
-
- `--ids-only` — one id per line.
|
|
69
|
-
- `--count` — a single integer.
|
|
70
|
-
- `--markdown` — human preview (NOT JSON, do not parse).
|
|
71
|
-
- `--jq <expr>` — tiny path filter: `.a`, `.a.b`, `.a[]`, `.a[].b`, `.a[0]`, `.`. **Pipes (`|`), string interpolation (`\(.x)`), and object/array projection (`{…}`, `[.]`) are NOT supported** — pipe through real `jq` after `--quiet` if you need those.
|
|
72
|
-
|
|
73
|
-
Errors **always** appear on stderr with full envelope, bypassing `--jq`. Exit codes:
|
|
74
|
-
|
|
75
|
-
| Code | Meaning |
|
|
76
|
-
|------|---------|
|
|
77
|
-
| 0 | success |
|
|
78
|
-
| 2 | not found |
|
|
79
|
-
| 3 | auth failure |
|
|
80
|
-
| 4 | forbidden / missing scope |
|
|
81
|
-
| 5 | rate-limited |
|
|
82
|
-
| 6 | network / timeout |
|
|
83
|
-
| 7 | validation |
|
|
84
|
-
| 8 | ambiguous ("which one did you mean?") |
|
|
85
|
-
| 9 | conflict / idempotency key mismatch |
|
|
86
|
-
| 10 | business rule violation |
|
|
87
|
-
|
|
88
|
-
## Work as an agent, not a human
|
|
89
|
-
|
|
90
|
-
1. **Preflight ritual antes de `task create` (OBLIGATORIO)**. Una sola llamada antes de cualquier creación de tarea — el server hace fan-out por ti:
|
|
91
|
-
|
|
92
|
-
```bash
|
|
93
|
-
crm task preflight \
|
|
94
|
-
--title "Arreglar H1 en /pricing" \
|
|
95
|
-
--url https://example.com/pricing \
|
|
96
|
-
--domain dom_xyz \
|
|
97
|
-
--jq .data.hints
|
|
98
|
-
```
|
|
99
|
-
|
|
100
|
-
El envelope trae
|
|
101
|
-
`similarTasks` (FTS por título re-rankeado por Jaccard + recencia + same-domain), `recall` (cuando pasas `--url`), `recentChanges`, `urlScopedTasks`, `recentBacklinks`, `openTaskCounts
|
|
102
|
-
|
|
103
|
-
- Si `hints[0]` empieza por **"Posible duplicado"** → **PARA**. Lee la tarea con `crm task get <id>` y decide: editar la existente, comentar en ella, o (si de verdad es trabajo nuevo) crear citando la otra con `#[Title](id)`.
|
|
104
|
-
- Si `urlScopedTasks` no está vacío → la URL ya tiene cargas abiertas; añade un comentario o referencia, no dupliques.
|
|
105
|
-
- Si `openTaskCounts.todo + .doing + .blocked >= 8` → el dominio está sobrecargado; pregunta al humano antes de añadir más.
|
|
106
|
-
- `recentChanges` te dice qué se editó en esa URL/dominio últimamente — si tu tarea coincide con un cambio reciente, casi seguro ya está hecha o en curso.
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
crm
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
- **
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
-
|
|
138
|
-
-
|
|
139
|
-
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
-
|
|
144
|
-
-
|
|
145
|
-
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
|
155
|
-
|
|
|
156
|
-
|
|
|
157
|
-
|
|
|
158
|
-
| Chat
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
crm
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
###
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
crm
|
|
367
|
-
--
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
crm
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
crm
|
|
397
|
-
crm
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
crm
|
|
417
|
-
crm
|
|
418
|
-
|
|
419
|
-
crm
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
crm
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
crm
|
|
426
|
-
crm
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
crm
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
|
|
448
|
-
|
|
449
|
-
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
-
|
|
473
|
-
-
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
|
|
482
|
-
|
|
483
|
-
|
|
484
|
-
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
crm
|
|
489
|
-
|
|
490
|
-
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
##
|
|
494
|
-
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
|
|
508
|
-
|
|
509
|
-
|
|
510
|
-
|
|
511
|
-
|
|
512
|
-
|
|
513
|
-
|
|
514
|
-
|
|
515
|
-
|
|
516
|
-
|
|
517
|
-
|
|
518
|
-
crm
|
|
519
|
-
|
|
520
|
-
|
|
521
|
-
|
|
522
|
-
|
|
523
|
-
|
|
524
|
-
|
|
525
|
-
|
|
526
|
-
|
|
527
|
-
|
|
528
|
-
|
|
529
|
-
|
|
530
|
-
|
|
531
|
-
|
|
532
|
-
|
|
533
|
-
|
|
534
|
-
|
|
535
|
-
|
|
536
|
-
crm
|
|
537
|
-
|
|
538
|
-
|
|
539
|
-
|
|
540
|
-
|
|
541
|
-
|
|
542
|
-
|
|
543
|
-
|
|
544
|
-
|
|
545
|
-
|
|
546
|
-
|
|
547
|
-
|
|
548
|
-
crm
|
|
549
|
-
|
|
550
|
-
crm
|
|
551
|
-
|
|
552
|
-
|
|
553
|
-
|
|
554
|
-
|
|
555
|
-
|
|
556
|
-
|
|
557
|
-
|
|
558
|
-
|
|
559
|
-
|
|
560
|
-
|
|
561
|
-
|
|
562
|
-
|
|
563
|
-
|
|
564
|
-
|
|
565
|
-
|
|
566
|
-
|
|
567
|
-
|
|
568
|
-
|
|
569
|
-
|
|
570
|
-
|
|
571
|
-
|
|
572
|
-
|
|
573
|
-
|
|
574
|
-
|
|
575
|
-
|
|
576
|
-
|
|
577
|
-
|
|
578
|
-
|
|
579
|
-
|
|
580
|
-
|
|
581
|
-
|
|
582
|
-
|
|
583
|
-
|
|
584
|
-
|
|
585
|
-
|
|
586
|
-
|
|
587
|
-
|
|
1
|
+
---
|
|
2
|
+
name: crm
|
|
3
|
+
description: Drive the ROILab SEO+CRM from a shell. Tasks, comments, file attachments, chat threads, analytics, backlinks, change events, and cross-entity recall — every action is auditable and attributed to you as an agent.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# `crm` — CLI for AI agents + humans
|
|
7
|
+
|
|
8
|
+
This skill teaches you to operate the ROILab SEO+CRM via the `crm` binary. All writes you make are stamped `actorType: "agent"` and associated with your API key, so there is a robot badge next to your changes in the web UI. Humans can filter and review what you did.
|
|
9
|
+
|
|
10
|
+
## Capabilities you might miss (flags, not verbs)
|
|
11
|
+
|
|
12
|
+
Some features ship as **flags on existing commands**, not as new subcommands —
|
|
13
|
+
if you only list verbs (`crm task --help`) you won't see them. Look for these:
|
|
14
|
+
|
|
15
|
+
| Flag | Where | What it does |
|
|
16
|
+
|---|---|---|
|
|
17
|
+
| `--file <path...>` | `crm task create` / `task update` / `comment create` / `chat send` / `chat reply` | Adjunta archivo(s) en la misma escritura. Repetible. Máx 10 MB; aviso desde 2 MB. Detalles en "Adjuntar archivos" más abajo. |
|
|
18
|
+
| `--shadow` | cualquier write | Fuerza propuesta pendiente de revisión humana. |
|
|
19
|
+
| `--wait-for-approval --timeout 30m` | cualquier write con shadow | Bloquea hasta que un humano decida. |
|
|
20
|
+
| `--idempotency-key <key>` | cualquier write | Reintentos seguros entre invocaciones. |
|
|
21
|
+
| `--ids-only` / `--quiet` / `--count` / `--markdown` / `--jq <expr>` | cualquier comando | Modos de salida (mutuamente excluyentes salvo `--jq`). |
|
|
22
|
+
|
|
23
|
+
Si dudas si una capacidad existe, **revisa los flags de cada verbo**
|
|
24
|
+
(`crm <noun> <verb> --help`), no sólo la lista de verbos. También puedes
|
|
25
|
+
grepear `cli/SURFACE.txt` (envoltura plana de la superficie).
|
|
26
|
+
|
|
27
|
+
## Getting started
|
|
28
|
+
|
|
29
|
+
Two ways to authenticate, pick the one that matches your environment.
|
|
30
|
+
|
|
31
|
+
**Device flow — for human-driven use (recommended):**
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
crm auth login --api-url https://crm.roilab.es
|
|
35
|
+
# Prints a URL + 8-char code. Open the URL in your already-signed-in
|
|
36
|
+
# browser and click "Approve". The CLI polls and stores a 1-hour access
|
|
37
|
+
# token + 30-day refresh token. Tokens auto-rotate; nothing long-lived
|
|
38
|
+
# ends up on disk.
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
**API key — for unattended use (CI, agents-as-a-service):**
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
export CRM_API_KEY=crm_ak_... # or crm auth login crm_ak_...
|
|
45
|
+
crm doctor # verify reachability + auth
|
|
46
|
+
crm task list --status todo --limit 5
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
API keys are long-lived and workspace-scoped; leak-sensitive. Prefer the
|
|
50
|
+
device flow for interactive use; use raw keys only where a browser isn't
|
|
51
|
+
available.
|
|
52
|
+
|
|
53
|
+
If you need a new API key, ask the human to visit `Settings → Developers
|
|
54
|
+
→ API Keys` in the web UI and share one.
|
|
55
|
+
|
|
56
|
+
## Output contract — read this carefully
|
|
57
|
+
|
|
58
|
+
Every command emits a JSON envelope. Use `--jq` for filtering, **never pipe to `jq`**:
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
crm task list --jq '.data[].title' # OK
|
|
62
|
+
crm task list | jq '.data[].title' # WRONG — the envelope matters
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
Flags (mutually exclusive except `--jq`):
|
|
66
|
+
- `--json` — default. Full envelope with `ok`, `data`, `summary`, `breadcrumbs`, `meta`.
|
|
67
|
+
- `--quiet` — just `data`. Good for pipelines.
|
|
68
|
+
- `--ids-only` — one id per line.
|
|
69
|
+
- `--count` — a single integer.
|
|
70
|
+
- `--markdown` — human preview (NOT JSON, do not parse).
|
|
71
|
+
- `--jq <expr>` — tiny path filter: `.a`, `.a.b`, `.a[]`, `.a[].b`, `.a[0]`, `.`. **Pipes (`|`), string interpolation (`\(.x)`), and object/array projection (`{…}`, `[.]`) are NOT supported** — pipe through real `jq` after `--quiet` if you need those.
|
|
72
|
+
|
|
73
|
+
Errors **always** appear on stderr with full envelope, bypassing `--jq`. Exit codes:
|
|
74
|
+
|
|
75
|
+
| Code | Meaning |
|
|
76
|
+
|------|---------|
|
|
77
|
+
| 0 | success |
|
|
78
|
+
| 2 | not found |
|
|
79
|
+
| 3 | auth failure |
|
|
80
|
+
| 4 | forbidden / missing scope |
|
|
81
|
+
| 5 | rate-limited |
|
|
82
|
+
| 6 | network / timeout |
|
|
83
|
+
| 7 | validation |
|
|
84
|
+
| 8 | ambiguous ("which one did you mean?") |
|
|
85
|
+
| 9 | conflict / idempotency key mismatch |
|
|
86
|
+
| 10 | business rule violation |
|
|
87
|
+
|
|
88
|
+
## Work as an agent, not a human
|
|
89
|
+
|
|
90
|
+
1. **Preflight ritual antes de `task create` (OBLIGATORIO)**. Una sola llamada antes de cualquier creación de tarea — el server hace fan-out por ti:
|
|
91
|
+
|
|
92
|
+
```bash
|
|
93
|
+
crm task preflight \
|
|
94
|
+
--title "Arreglar H1 en /pricing" \
|
|
95
|
+
--url https://example.com/pricing \
|
|
96
|
+
--domain dom_xyz \
|
|
97
|
+
--jq .data.hints
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
El envelope trae 7 secciones acotadas (≤5 items por defecto):
|
|
101
|
+
`similarTasks` (FTS por título re-rankeado por Jaccard + recencia + same-domain), `recall` (cuando pasas `--url`), `recentChanges`, `urlScopedTasks`, `recentBacklinks`, `openTaskCounts`, `suggestedSkills` (playbooks de agencia que matchean el título — staff only). Y `hints[]` — cadenas en español que el agente lee primero. Reglas:
|
|
102
|
+
|
|
103
|
+
- Si `hints[0]` empieza por **"Posible duplicado"** → **PARA**. Lee la tarea con `crm task get <id>` y decide: editar la existente, comentar en ella, o (si de verdad es trabajo nuevo) crear citando la otra con `#[Title](id)`.
|
|
104
|
+
- Si `urlScopedTasks` no está vacío → la URL ya tiene cargas abiertas; añade un comentario o referencia, no dupliques.
|
|
105
|
+
- Si `openTaskCounts.todo + .doing + .blocked >= 8` → el dominio está sobrecargado; pregunta al humano antes de añadir más.
|
|
106
|
+
- `recentChanges` te dice qué se editó en esa URL/dominio últimamente — si tu tarea coincide con un cambio reciente, casi seguro ya está hecha o en curso.
|
|
107
|
+
- Si `suggestedSkills` trae algo (o ves el hint "Skill recomendada") → hay un playbook de agencia para este tipo de tarea; **cárgalo con `crm skill pull <slug>` y síguelo** antes de ejecutar. No improvises el método.
|
|
108
|
+
|
|
109
|
+
**No pre-crawlees.** Para entender el contenido de una URL específica usa `WebFetch` sobre la URL puntual (1 GET) — Screaming Frog se reserva para auditorías de dominio completas. Para datos GSC/GA4 puntuales (clicks/impr/CTR/posición de la URL), tira `crm gsc query --filters "page=<url>"` o `crm ga4 query --filters "pagePath=<url>"` después del preflight, no antes — solo si el preflight indica que merece crear la tarea.
|
|
110
|
+
|
|
111
|
+
`crm recall` sigue existiendo como herramienta cruda para análisis post-hoc; el preflight ya la incluye.
|
|
112
|
+
|
|
113
|
+
2. **Log decisions explicitly**. Comments default to `--kind=agent_log` for you (a minor trace). When you *chose* a course of action, use `--kind=decision`:
|
|
114
|
+
```bash
|
|
115
|
+
crm comment create --task tsk_abc --kind decision \
|
|
116
|
+
--body "Chose to revert meta title; A/B showed −8% CTR in 14d"
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
3. **Mark completed tasks explicitly**. Pair the status change with a `--kind decision` comment that explains the outcome — that's what the UI surfaces as the closing summary:
|
|
120
|
+
```bash
|
|
121
|
+
crm task update tsk_abc --status done
|
|
122
|
+
crm comment create --task tsk_abc --kind decision \
|
|
123
|
+
--body "Cerrado: H1 reemplazado, A/B +12% CTR a 14d (ver crm change list)"
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
4. **Use `reviewRequired`**. Your task creates default to `reviewRequired=true` — the human sees them in a dedicated inbox section. Only pass `--no-review` for low-stakes rework (e.g. re-filing a recurring instance). (The flag has only been wired end-to-end since 0.6.0 — earlier CLIs sent it but the server stripped it.)
|
|
127
|
+
|
|
128
|
+
**Read side — when you see `reviewRequired: true` on a task you didn't create**: treat it as tentative. The row is live but a human hasn't acknowledged it yet, and may still edit, reassign, or reject the framing. Don't build downstream work that assumes it's settled (no offers linked to it, no auto-complete on its goals, no marking siblings as duplicates of it). You can't approve your own writes — only humans clear the flag. If you're blocked waiting, leave a `--kind decision` agent_log comment, don't change status. Filter the queue with `crm task list --review-pending` (or `GET /tasks?reviewRequired=true`).
|
|
129
|
+
|
|
130
|
+
5. **Every write gets an idempotency key**. The CLI autogenerates one per invocation, so retries within a single command are safe. If you're orchestrating retries across invocations, pass `--idempotency-key <ulid>` so the retry replays instead of double-creating.
|
|
131
|
+
|
|
132
|
+
6. **You choose shadow or autonomous per write**. Every write has two possible fates:
|
|
133
|
+
- **autonomous** — the write lands live immediately.
|
|
134
|
+
- **shadow** — the write lands as a pending proposal; the human reviews + approves / rejects in `/dashboard/inbox` before it materialises.
|
|
135
|
+
|
|
136
|
+
How it gets decided on a single call:
|
|
137
|
+
- Your key has a per-action default (`autonomous` or `shadow`). Absence ⇒ `autonomous`.
|
|
138
|
+
- Pass `--shadow` on the command to *upgrade* this specific call into shadow (e.g. for risky or irreversible writes). This is strictly safer and **always honored**.
|
|
139
|
+
- You **cannot** downgrade a key's `shadow` default to autonomous on a per-call basis. If a human set your key to shadow-by-default for an action, they wanted review every time. If you need autonomy, ask the human to update the key policy.
|
|
140
|
+
- **Hard deny** (you cannot perform this action at all) is *not* a policy value — it's expressed via `scopes` on the key. A missing scope returns a plain 403; it never enters the shadow/autonomous decision.
|
|
141
|
+
|
|
142
|
+
Once a write is in shadow mode:
|
|
143
|
+
- `meta.approvalStatus === "pending"` on the envelope. Do not create follow-up work (comments, edits, change events) that depends on it being visible — it is not.
|
|
144
|
+
- Either poll with `crm review show <kind> <id>` until the status changes, or add `--wait-for-approval --timeout 30m` to the write so the CLI blocks for you.
|
|
145
|
+
- Check your own pending queue with `crm review list --mine`.
|
|
146
|
+
- The response envelope includes breadcrumbs: "Poll decision" (for you) and "View in Inbox" (for the human).
|
|
147
|
+
|
|
148
|
+
**Rule of thumb**: if the change is hard to reverse (deleting work, merging branches of logic, sending external messages, big content rewrites), pass `--shadow` even if your default is autonomous. Low-stakes routine updates (status nudges, agent_log comments, tag adjustments) can run autonomously.
|
|
149
|
+
|
|
150
|
+
7. **After every write that returns an id, surface the full dashboard URL to the human.** When you report a `create` or `update` result back in chat, paste the complete `https://crm.roilab.es/dashboard/<entity>/<id>` URL alongside the id so the human can copy-paste it straight into the browser. The CLI envelope returns the id in `data.id` (and `data._id` for tasks). Build the URL with the API root from the active profile (default `https://crm.roilab.es`; check `crm doctor` if unsure).
|
|
151
|
+
|
|
152
|
+
| Entity | URL template |
|
|
153
|
+
|---|---|
|
|
154
|
+
| Task | `https://crm.roilab.es/dashboard/tasks?taskId=<id>` |
|
|
155
|
+
| Backlink | `https://crm.roilab.es/dashboard/backlinks/<id>` |
|
|
156
|
+
| Domain | `https://crm.roilab.es/dashboard/domains/<id>` |
|
|
157
|
+
| Client | `https://crm.roilab.es/dashboard/clients/<id>` |
|
|
158
|
+
| Chat thread | `https://crm.roilab.es/dashboard/chat?t=<threadId>` |
|
|
159
|
+
| Chat message (deep link) | `https://crm.roilab.es/dashboard/chat?m=<messageId>` |
|
|
160
|
+
|
|
161
|
+
**Do NOT confuse this with `[[feedback_task_refs_use_chip_syntax]]`**: inside task descriptions, comments, and chat bodies you still use `#[Title](taskId)` chips, never raw dashboard URLs. The dashboard URL goes only in your chat reply to the human reviewing your work — that is where they need a one-click destination.
|
|
162
|
+
|
|
163
|
+
## Colocar tareas en columnas kanban (swimlanes por persona)
|
|
164
|
+
|
|
165
|
+
Algunos tableros usan **columnas personalizadas** — una por redactor/persona —
|
|
166
|
+
con `autoAssignUserId` configurado. Para mover una tarea a la columna de alguien
|
|
167
|
+
y que quede asignada en un solo paso:
|
|
168
|
+
|
|
169
|
+
1. `crm board columns <boardId>` — lista las columnas con su `autoAssignUserId`
|
|
170
|
+
y `autoMoveOnAssign`. Resuelve qué columna corresponde a cada persona.
|
|
171
|
+
2. `crm task update <taskId> --column <columnId>` — coloca la tarea en esa
|
|
172
|
+
columna. Adopta el `status` de la columna y aplica su auto-asignación (si la
|
|
173
|
+
columna auto-asigna a un usuario cliente, también marca `clientVisible`).
|
|
174
|
+
|
|
175
|
+
Para leer el backlog de un tablero (p. ej. la columna "To Do" de un board de
|
|
176
|
+
redactores) usa `crm task list --board <boardId> --column <toDoColumnId>`.
|
|
177
|
+
|
|
178
|
+
> Nota: `--column` solo admite columnas del **mismo board** que la tarea. La
|
|
179
|
+
> tarea sigue con `reviewRequired` si fue creada por agente — staff debe
|
|
180
|
+
> aceptarla para que el redactor cliente la vea en el portal.
|
|
181
|
+
|
|
182
|
+
## Mentioning humans + linking tasks
|
|
183
|
+
|
|
184
|
+
Comments and task descriptions are markdown. Two special syntaxes — both
|
|
185
|
+
already wired up to fan out the right side effects when the row lands live:
|
|
186
|
+
|
|
187
|
+
- **`@[Name](memberId)`** — pings a workspace member. Fires a
|
|
188
|
+
`comment_mentioned` notification + email. **Important authorization side
|
|
189
|
+
effect:** mentioning a `client` user auto-grants them domain access for
|
|
190
|
+
this task. Mentioning a `client_lead` outside their own client is rejected.
|
|
191
|
+
- **`#[Title](taskId)`** — adds a graph edge between tasks (parent / blocker
|
|
192
|
+
/ duplicate-of / follow-up). Updates the target's "Referenced by" panel.
|
|
193
|
+
No notification fires — purely a graph operation.
|
|
194
|
+
|
|
195
|
+
### Anti-pattern: NEVER reference a task by bare id
|
|
196
|
+
|
|
197
|
+
Whenever you mention another task — in a description, a comment, a
|
|
198
|
+
`## Tareas relacionadas` block, an audit trail, anywhere markdown is
|
|
199
|
+
rendered — use the chip syntax `#[Título](taskId)`. **A bare id in
|
|
200
|
+
backticks is dead text**: no clickable link, no graph edge, no
|
|
201
|
+
"Referenced by" entry, and human readers have to copy-paste it into the
|
|
202
|
+
URL bar to navigate.
|
|
203
|
+
|
|
204
|
+
```markdown
|
|
205
|
+
❌ Bad — `m172v5tesszx27fhbfmj7abb45868z64` — "Modificar hreflang en dominio .NET"
|
|
206
|
+
❌ Bad — https://crm.roilab.es/dashboard/tasks?taskId=m172v5tesszx27fhbfmj7abb45868z64
|
|
207
|
+
✅ Good — #[Modificar hreflang en dominio .NET](m172v5tesszx27fhbfmj7abb45868z64)
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
This applies equally to inline mentions and to lists. A `## Tareas
|
|
211
|
+
relacionadas` bullet must lead with the chip, not with the id:
|
|
212
|
+
|
|
213
|
+
```markdown
|
|
214
|
+
- #[Eliminar hreflang chile de la home y ajustar hreflang es](m1716nym1jej9vevfnmgp6yzhn869vbz) (done 2024-05-30) → quitó `hreflang="es-CL"`…
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
Special characters in the title (`[`, `]`, parens) must be backslash-escaped
|
|
218
|
+
so the markdown round-trips through the tokenizer:
|
|
219
|
+
|
|
220
|
+
```markdown
|
|
221
|
+
#[\[GB\] Eliminar hreflangs apuntando hacia growbarato.it](m1767y1wqrz93q3kvqtej350398695fj)
|
|
222
|
+
#[Añadir nuevo schema Carousel \(ItemList\) en categorías](m178j0p99dwmfcwy37c0jr9t3s86819z)
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
When you don't know the title off the top of your head, **resolve it
|
|
226
|
+
first** — see the next subsection. Don't fall back to a bare id "for now";
|
|
227
|
+
you'll forget to come back.
|
|
228
|
+
|
|
229
|
+
### Resolve IDs before composing
|
|
230
|
+
|
|
231
|
+
Don't hand-roll memberIds or taskIds. Use the resolver helpers; they exit
|
|
232
|
+
non-zero when the query is wrong:
|
|
233
|
+
|
|
234
|
+
```bash
|
|
235
|
+
# Resolve a name → markdown chip. Exits 8 if ambiguous, 2 if no match.
|
|
236
|
+
crm mention member "luis" # → @[Luis Fernández](mem_abc)
|
|
237
|
+
crm mention member --domain dom_xyz "sarah"
|
|
238
|
+
crm mention task "fix h1 pricing" # → #[Fix H1 on /pricing](tsk_xyz)
|
|
239
|
+
|
|
240
|
+
# Or list candidates first if you want to pick by hand:
|
|
241
|
+
crm member list --query "luis"
|
|
242
|
+
crm member list --domain dom_xyz --role member,admin
|
|
243
|
+
crm task search "h1" --limit 10
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
Compose into a write with shell substitution — the chips are plain markdown,
|
|
247
|
+
not JSON:
|
|
248
|
+
|
|
249
|
+
```bash
|
|
250
|
+
crm comment create --task tsk_abc \
|
|
251
|
+
--body "$(crm mention member luis) please check the audit results — \
|
|
252
|
+
blocking $(crm mention task 'crawl audit GB')"
|
|
253
|
+
```
|
|
254
|
+
|
|
255
|
+
If the resolver exits 8 the shell substitution captures stderr (not stdout),
|
|
256
|
+
so the outer command will land with a literal empty chip — that's the
|
|
257
|
+
intended failure mode. Read the stderr disambiguation hint and re-run.
|
|
258
|
+
|
|
259
|
+
### Assemble context BEFORE mentioning anything
|
|
260
|
+
|
|
261
|
+
The legitimate pool of mentionable members for a write is **the union of**:
|
|
262
|
+
the existing task's assignees + collaborators (already inlined as
|
|
263
|
+
`participants` on `crm task get`), the staff returned by `crm brief`, and
|
|
264
|
+
anyone the human explicitly named. Anything outside that pool is almost
|
|
265
|
+
always the wrong person — ask before mentioning.
|
|
266
|
+
|
|
267
|
+
```bash
|
|
268
|
+
# For an existing task: pulls participants (with role + expertise) + parent
|
|
269
|
+
# domain brief + cross-references already linked. Run this BEFORE adding a
|
|
270
|
+
# comment.
|
|
271
|
+
crm brief --task tsk_abc
|
|
272
|
+
|
|
273
|
+
# For a new task: scope to the domain so the staff list is the working pool.
|
|
274
|
+
crm brief --domain dom_xyz
|
|
275
|
+
|
|
276
|
+
# For "is there already a task tracking this?" before adding a #link:
|
|
277
|
+
crm task related tsk_abc # tasks already linked + same-domain + shared-tags
|
|
278
|
+
crm recall https://example.com/pricing
|
|
279
|
+
```
|
|
280
|
+
|
|
281
|
+
`crm brief --task` is the URL-equivalent of `recall` for tasks: the right
|
|
282
|
+
pre-write context every time.
|
|
283
|
+
|
|
284
|
+
#### Sensitive handling notes
|
|
285
|
+
|
|
286
|
+
Profile responses carry an `internalNotes` field (markdown, staff-only) on
|
|
287
|
+
clients, domains and members. Treat it as binding handling guidance, not
|
|
288
|
+
flavour text — it's where the human team writes things like "never mention
|
|
289
|
+
project X to this CEO", "always cc Eric Collado as follower on every task",
|
|
290
|
+
"careful — this person prefers blunt feedback". Always read these before
|
|
291
|
+
drafting any comment, mention or task that touches the entity. They flow
|
|
292
|
+
through automatically on:
|
|
293
|
+
|
|
294
|
+
- `crm brief <clientId>` → `clientProfile.internalNotes` and per-domain / per-staff notes
|
|
295
|
+
- `crm brief --domain <id>` → domain + parent client + staff with activity
|
|
296
|
+
- `crm brief --task <id>` → each `participants[].internalNotes` + parent domain + parent client
|
|
297
|
+
- `crm client profile <id>` / `domain profile <id>` / `member profile <id>` → single-entity fetch
|
|
298
|
+
- `crm task get <id>` → `participants[].internalNotes` for staff callers
|
|
299
|
+
|
|
300
|
+
Never echo `internalNotes` into client-visible surfaces (shared chat threads,
|
|
301
|
+
client-visible tasks, replies through the portal). They are agency-internal.
|
|
302
|
+
|
|
303
|
+
### When to mention vs. not
|
|
304
|
+
|
|
305
|
+
- **Mention** when attention is genuinely needed *now*: a decision blocking
|
|
306
|
+
next steps, a completed item awaiting review, a regression you've spotted.
|
|
307
|
+
- **Don't mention** on routine `agent_log` traces ("ran the audit, here's
|
|
308
|
+
the output"). The volume drowns inboxes; the badge already shows it's
|
|
309
|
+
agent work.
|
|
310
|
+
- **`#`-link** when the relationship is real graph (blocker, duplicate-of,
|
|
311
|
+
follow-up). Not as decoration, not to "show your work" — that goes in
|
|
312
|
+
prose.
|
|
313
|
+
- **Self-mentions are filtered server-side** so you don't ping your own
|
|
314
|
+
underlying member.
|
|
315
|
+
|
|
316
|
+
### Notifications fire on approval, not on submission
|
|
317
|
+
|
|
318
|
+
This is the rule that matters for shadow-mode writes:
|
|
319
|
+
|
|
320
|
+
- **Autonomous write** with `@[Name](id)` → notification fires immediately,
|
|
321
|
+
scope grants apply immediately, `taskMentions` index updates immediately.
|
|
322
|
+
- **Shadow proposal** with `@[Name](id)` → **nothing fires until a human
|
|
323
|
+
approves**. The chip renders to reviewers in the markdown so they can see
|
|
324
|
+
the intent, but the mentioned user is not pinged, no scope is granted, no
|
|
325
|
+
graph edge lands. On approval, all three side effects fire — attributed
|
|
326
|
+
to the original agent's name (so the user reads "Agent X mentioned you")
|
|
327
|
+
but the notification's `createdAt` is the approval moment.
|
|
328
|
+
- **Shadow proposal that's rejected** → side effects never fire. The chip
|
|
329
|
+
goes nowhere.
|
|
330
|
+
|
|
331
|
+
The point: a `--shadow` write that mentions someone is not a way to "ping
|
|
332
|
+
them with a heads-up before review." It's a deferred mention. If you need
|
|
333
|
+
the human aware before approval, write a `--kind decision` autonomous
|
|
334
|
+
comment.
|
|
335
|
+
|
|
336
|
+
### Edits to descriptions are diffed
|
|
337
|
+
|
|
338
|
+
Updating a task's description with a new `@mention` only fires for the
|
|
339
|
+
**newly added** mention, not the ones already present. Same for `#`-links.
|
|
340
|
+
You can safely edit a description that already references people without
|
|
341
|
+
re-pinging them.
|
|
342
|
+
|
|
343
|
+
## Adjuntar archivos
|
|
344
|
+
|
|
345
|
+
Cuatro comandos aceptan `--file <ruta>` (repetible) y suben el archivo a
|
|
346
|
+
Convex storage antes de enviar la escritura:
|
|
347
|
+
|
|
348
|
+
- `crm chat send <threadId> --file <ruta>` y `crm chat reply <msgId> --thread <id> --file <ruta>`
|
|
349
|
+
- `crm task create --file <ruta>` y `crm task update <id> --file <ruta>`
|
|
350
|
+
- `crm comment create --task <id> --file <ruta>`
|
|
351
|
+
|
|
352
|
+
El flujo siempre es el mismo (dos pasos: URL firmada → `POST` directo a Convex
|
|
353
|
+
storage). Reglas y límites compartidos:
|
|
354
|
+
|
|
355
|
+
- **Máx 10 MB por archivo** — el CLI rechaza localmente antes de tocar la red.
|
|
356
|
+
- **Aviso a partir de 2 MB** en stderr (`[AVISO] ... la subida puede tardar.`).
|
|
357
|
+
- MIME se sniffa por extensión; lo desconocido viaja como `application/octet-stream`,
|
|
358
|
+
que el servidor acepta y la UI renderiza como tarjeta genérica.
|
|
359
|
+
- `--body` (chat / comentario) es opcional si pasas `--file` (mensajes /
|
|
360
|
+
comentarios sólo-archivos están permitidos).
|
|
361
|
+
- **Cuidado con `task update --file`**: la lista de adjuntos es REEMPLAZO,
|
|
362
|
+
no merge. Los archivos previos desaparecen. Para vaciar explícitamente, usa
|
|
363
|
+
`--clear-files`; para conservar los previos hay que pasarlos también.
|
|
364
|
+
- **Para añadir/quitar UN archivo sin tocar el resto** usa `task attach` en vez
|
|
365
|
+
de `task update --file` (que reemplaza toda la lista):
|
|
366
|
+
- `crm task attach list <taskId>` — lista los adjuntos (con su `_id`).
|
|
367
|
+
- `crm task attach add <taskId> --file <ruta...>` — añade sin clobber.
|
|
368
|
+
- `crm task attach remove <taskId> <attachmentId>` — quita uno por id.
|
|
369
|
+
Tope: 50 archivos/tarea. Los clientes pueden adjuntar a tareas que ven.
|
|
370
|
+
|
|
371
|
+
```bash
|
|
372
|
+
# Chat
|
|
373
|
+
crm chat send "$TID" --body "captura del 404" --file ./bug.png
|
|
374
|
+
crm chat reply <msgId> --thread "$TID" --file ./report.pdf --file ./logs.txt
|
|
375
|
+
|
|
376
|
+
# Tarea — en la creación / reemplazo total
|
|
377
|
+
crm task create --title "Migración H1" --domain dom_xyz --file ./brief.pdf
|
|
378
|
+
crm task update tsk_abc --file ./new-spec.pdf --clear-files
|
|
379
|
+
|
|
380
|
+
# Tarea — gestión incremental de adjuntos (sin reemplazar la lista)
|
|
381
|
+
crm task attach add tsk_abc --file ./extra.pdf --file ./shot.png
|
|
382
|
+
crm task attach list tsk_abc
|
|
383
|
+
crm task attach remove tsk_abc att_xyz
|
|
384
|
+
|
|
385
|
+
# Comentario
|
|
386
|
+
crm comment create --task tsk_abc --kind decision \
|
|
387
|
+
--body "Cerrado: ver diff y screenshots" \
|
|
388
|
+
--file ./before.png --file ./after.png
|
|
389
|
+
```
|
|
390
|
+
|
|
391
|
+
## Common recipes
|
|
392
|
+
|
|
393
|
+
```bash
|
|
394
|
+
# Read-only triage before acting
|
|
395
|
+
crm task preflight --title "Fix H1 on /pricing" --url https://example.com/pricing --domain dom_xyz
|
|
396
|
+
crm change list --domain dom_xyz --url /pricing --jq '.data[].items[].type'
|
|
397
|
+
crm backlink lost --domain dom_xyz --since 2026-01-01 --count
|
|
398
|
+
|
|
399
|
+
# Create a measured task — sólo si el preflight no encontró duplicados
|
|
400
|
+
crm task create \
|
|
401
|
+
--title "Fix H1 on /pricing" \
|
|
402
|
+
--domain dom_xyz \
|
|
403
|
+
--description "Current H1 buries the value prop; replace with 'Plans that scale with you'." \
|
|
404
|
+
--idempotency-key 01HY8X...
|
|
405
|
+
|
|
406
|
+
# Log change events after shipping — SOLO en tareas de Redacción (kind:
|
|
407
|
+
# "content"). Las tareas generales no registran cambios on-page y el backend
|
|
408
|
+
# los rechaza. No hay verbo CLI todavía; hit the REST endpoint directly:
|
|
409
|
+
# POST /api/v1/domains/<domainId>/changes (autogenerates an idempotency key
|
|
410
|
+
# per call; same envelope contract).
|
|
411
|
+
|
|
412
|
+
# Search across everything
|
|
413
|
+
crm search "meta title" --kind change --domain dom_xyz --limit 5
|
|
414
|
+
|
|
415
|
+
# Live provider-API queries (tokens stay on the server)
|
|
416
|
+
crm integration list --quiet | jq -r '.[] | "\(._id) \(.provider) \(.services|join(","))"'
|
|
417
|
+
crm gsc query --property prop_abc --dimension page \
|
|
418
|
+
--filters "page contains /blog/" --start 2026-03-01 --end 2026-04-01 --limit 50
|
|
419
|
+
crm ga4 query --property prop_abc --start 2026-03-01 --end 2026-04-01 \
|
|
420
|
+
--filters "pagePath contains /pricing"
|
|
421
|
+
crm bing query --property prop_bing --start 2026-03-01 --end 2026-04-01
|
|
422
|
+
crm integration sync --property prop_abc # forces fresh ingestion (15m cooldown)
|
|
423
|
+
|
|
424
|
+
# Google Ads — discover, analyse, manage budgets (staff-only, cost is sensitive)
|
|
425
|
+
crm ads accounts --account acc_google # enumerate MCC child accounts (customerId/name/currency)
|
|
426
|
+
crm ads campaigns --property prop_ads --start 2026-06-01 --end 2026-06-30 \
|
|
427
|
+
--compare-start 2026-05-01 --compare-end 2026-05-31 # per-campaign CPA/ROAS + PoP deltas
|
|
428
|
+
# Proactive intelligence: anomalies across ALL ads accounts (omit --property), vs the prior period
|
|
429
|
+
crm ads anomalies --start 2026-06-01 --end 2026-06-30 \
|
|
430
|
+
--compare-start 2026-05-01 --compare-end 2026-05-31 --jq '.data.anomalies'
|
|
431
|
+
# Budget pacing: MTD spend vs budget + end-of-month projection (pass the month bounds explicitly)
|
|
432
|
+
crm ads pacing --month-start 2026-06-01 --as-of 2026-06-29
|
|
433
|
+
crm ads budget --property prop_ads # read budget
|
|
434
|
+
crm ads budget --property prop_ads --set 3000 # set / --clear to remove
|
|
435
|
+
crm ads import # trigger a fresh Ads ingestion pass
|
|
436
|
+
|
|
437
|
+
# Agency skills — read the library + sync it to disk so Claude Code picks it up
|
|
438
|
+
crm skill list --category local-seo --quiet # all published in category
|
|
439
|
+
crm skill show auditoria-seo-local # metadata + revision id
|
|
440
|
+
crm skill revisions auditoria-seo-local # publish history
|
|
441
|
+
crm skill revision <revisionId> # single immutable revision
|
|
442
|
+
crm skill pull --all # writes .claude/skills/<slug>/SKILL.md
|
|
443
|
+
crm skill update # refresh any outdated skill
|
|
444
|
+
crm skill diff auditoria-seo-local # local vs remote state
|
|
445
|
+
|
|
446
|
+
# Agency skills — authoring (owner / admin / member with skills:write)
|
|
447
|
+
crm skill create --slug my-playbook --name "Mi playbook" \
|
|
448
|
+
--description "Cuándo y cómo aplicarlo" --category content
|
|
449
|
+
crm skill set my-playbook --visibility staff_only # metadata-only PATCH
|
|
450
|
+
crm skill push my-playbook --note "primera revisión" --publish # body+frontmatter
|
|
451
|
+
crm skill archive my-playbook # hide from library
|
|
452
|
+
crm skill restore my-playbook # un-archive
|
|
453
|
+
|
|
454
|
+
# Chat — read threads, post messages, react, attach files (max 10 MB each)
|
|
455
|
+
crm chat list --scope client --client cli_abc
|
|
456
|
+
crm chat get <threadId> --message-limit 50 # metadata + recent msgs
|
|
457
|
+
crm chat read <threadId> --page-limit 50 --before <ms> # paginate backwards
|
|
458
|
+
crm chat send <threadId> --body "$(crm mention member luis) revisado"
|
|
459
|
+
crm chat send <threadId> --body "informe adjunto" --file ./audit.pdf --file ./serp.png
|
|
460
|
+
crm chat reply <messageId> --thread <threadId> --body "ok, mañana"
|
|
461
|
+
crm chat react <messageId> --emoji "👀" # toggle (re-run unreacts)
|
|
462
|
+
crm chat dm --member mem_xyz --title "1:1 review"
|
|
463
|
+
crm chat mark-read <threadId>
|
|
464
|
+
```
|
|
465
|
+
|
|
466
|
+
## Playbooks de tarea incluidos en este paquete
|
|
467
|
+
|
|
468
|
+
Este paquete trae playbooks en `skill-bundles/tools/<name>/SKILL.md` — viajan
|
|
469
|
+
con el CLI, así que sólo quien se baja/actualiza el CLI los tiene. Cuando una
|
|
470
|
+
tarea encaje con uno, **cárgalo y síguelo** (no improvises el método):
|
|
471
|
+
|
|
472
|
+
- **`tool-routing`** — matriz para elegir qué herramienta externa usar.
|
|
473
|
+
- **`task-preflight`** — cómo leer `crm task preflight` antes de crear tareas.
|
|
474
|
+
|
|
475
|
+
Además, la **librería de skills de la agencia** (Convex, no bundled) trae
|
|
476
|
+
playbooks que se bajan a `.claude/skills/` con `crm skill pull <slug>`:
|
|
477
|
+
|
|
478
|
+
- **`optimizar-metas`** — metodología para optimizar/validar **meta title +
|
|
479
|
+
meta description** de una URL: valida la KW en el Rank Tracker (Ahrefs **sin
|
|
480
|
+
gastar créditos**) → analiza GSC de la URL → clasifica la SERP y mira a los
|
|
481
|
+
competidores → **desambigua y caza canibalización** entre URLs propias, y sólo
|
|
482
|
+
entonces redacta. Para una tarea "Optimizar PDP / metas":
|
|
483
|
+
`crm skill pull optimizar-metas` y síguelo.
|
|
484
|
+
|
|
485
|
+
## Decision tree for analytics questions
|
|
486
|
+
|
|
487
|
+
1. **Rollups / trends** → `crm domain metrics <id> --start … --end …`. Reads from Tinybird; cheap and fast.
|
|
488
|
+
2. **Per-query / per-page breakdowns, or custom filters** → `crm gsc query` / `crm ga4 query`. Hits the live provider API through our backend; pass `--dimension page`, `--filters "…"`, `--cursor <n>` for pagination.
|
|
489
|
+
3. **Data must be fresher than the last daily cron** → `crm integration sync --property <id>`. Respects a 15m cooldown; returns `queued | cooldown | already_running` so you can branch instead of polling.
|
|
490
|
+
|
|
491
|
+
Prefer 1 over 2 when it answers the question — Tinybird reads don't touch provider quotas. Drop down to 2 only when you need the dimensional detail.
|
|
492
|
+
|
|
493
|
+
## Things that are not obvious
|
|
494
|
+
|
|
495
|
+
- Task ids start with `tsk_`, domains with `dom_`, scopes with `sco_`. You pass these as the first positional arg to `get`/`update`. Never pass a URL where an id is expected.
|
|
496
|
+
- **Scope comments are useful**: if a task has a scoped propertyLink (via `scopeId`), use `crm scope get <id>` to see the fingerprint + filters before assuming the KPI measurement window.
|
|
497
|
+
- **Provider tokens never reach you**. The CLI forwards `--filters`, `--start`, `--end` through our REST layer; Convex decrypts and calls GSC / GA4 / Bing server-side. If you need a shape our wrappers don't cover, open an endpoint — don't try to exfiltrate tokens.
|
|
498
|
+
- **Bing daily feed has no per-query/per-page breakdown**. `crm bing query` returns the aggregate with a `meta.note` saying so.
|
|
499
|
+
- Web UI paths: `/dashboard/tasks?taskId=<id>` for a specific task, `/dashboard/inbox` for your review queue, `/developers` for the endpoint catalog, `/dashboard/settings?tab=api-usage` for the provider-API usage log.
|
|
500
|
+
|
|
501
|
+
## Task participants — assignees vs collaborators
|
|
502
|
+
|
|
503
|
+
Two distinct member lists on every task:
|
|
504
|
+
|
|
505
|
+
- **`--assignee <id...>`** — the **responsible** parties. Their queue counts include this task; auto-assigned watchers; show up first in the UI.
|
|
506
|
+
- **`--collaborator <id...>`** — **followers**. They receive notifications for the task but are not responsible. Use this for stakeholders who need awareness without ownership (e.g. a domain lead reviewing what a member ships).
|
|
507
|
+
|
|
508
|
+
Both flags accept multiple values and exist on both `crm task create` and `crm task update`. **Lists replace** on update — pass the full set, not a diff. To clear, pass `--assignee` with no value? No — that's commander rejecting it. To clear, omit the flag (no change) or set the next intent explicitly.
|
|
509
|
+
|
|
510
|
+
Other task fields the CLI now passes end-to-end: `--start <date>`, `--completion-strategy <all|any|manual>`, `--board <id>` (move between kanban boards on update). See `crm task update --help` for the full set.
|
|
511
|
+
|
|
512
|
+
## Reading rejection feedback (iteration loop)
|
|
513
|
+
|
|
514
|
+
When a reviewer rejects your shadow proposal, the row carries `rejectionReason` (free text from the human) and `allowRetry` (true = revise + re-propose; false = drop the work item).
|
|
515
|
+
|
|
516
|
+
```bash
|
|
517
|
+
# Just the actionable ones — items the reviewer wants you to redo.
|
|
518
|
+
crm review feedback --retryable-only
|
|
519
|
+
|
|
520
|
+
# Everything that's been rejected for this API key, with reasons.
|
|
521
|
+
crm review feedback
|
|
522
|
+
```
|
|
523
|
+
|
|
524
|
+
Read this **before** assuming a rejected proposal is dead. The reviewer often wants a smaller scope, a different framing, or a citation you didn't include — not "never do this." If `allowRetry=false`, drop the work and don't re-propose without a human asking.
|
|
525
|
+
|
|
526
|
+
## Access requests — `crm access`
|
|
527
|
+
|
|
528
|
+
When a client (or an agent on a client key) spots a task in a chat thread and wants to see it, the flow is:
|
|
529
|
+
|
|
530
|
+
```bash
|
|
531
|
+
# Client side — file the request, citing the chat message that exposed the task.
|
|
532
|
+
crm access request <task-id> --via <message-id> --message "Need to review the H1 fix"
|
|
533
|
+
|
|
534
|
+
# Staff side — list pending, then approve or deny with a scope choice.
|
|
535
|
+
crm access list
|
|
536
|
+
crm access approve <request-id> --scope task # smallest blast radius
|
|
537
|
+
crm access approve <request-id> --scope board # whole board (for cross-client tasks)
|
|
538
|
+
crm access deny <request-id> --note "Task is internal QA"
|
|
539
|
+
```
|
|
540
|
+
|
|
541
|
+
The older `crm task {request-access,list-access-requests,approve-access,deny-access}` aliases still work for one release with a deprecation warning — prefer the canonical `crm access` namespace.
|
|
542
|
+
|
|
543
|
+
## Backlink human-QA
|
|
544
|
+
|
|
545
|
+
Linkbuilding rows can sit in a pending-review queue until staff verifies the source. Agents with `backlinks:verify` scope can drive the queue:
|
|
546
|
+
|
|
547
|
+
```bash
|
|
548
|
+
crm backlink pending --domain dom_xyz
|
|
549
|
+
crm backlink verify <id> # idempotent
|
|
550
|
+
crm backlink reject <id> --reason wrong_anchor --notes "Anchor text drifted to brand-only"
|
|
551
|
+
crm backlink rejection-report --client cli_xyz --since-days 90
|
|
552
|
+
```
|
|
553
|
+
|
|
554
|
+
Reasons are a closed catalog (`spammy_source | wrong_anchor | wrong_target | nofollow_unexpected | dead_on_arrival | duplicate | policy_violation | other`) — server validates and notifies the original creator.
|
|
555
|
+
|
|
556
|
+
### Manual health-status override
|
|
557
|
+
|
|
558
|
+
`status` (active/removed/nofollowed/…) is the automated probe's verdict; it's orthogonal to the verify/reject QA verdict above. When the crawler gets a row wrong, override it (audited):
|
|
559
|
+
|
|
560
|
+
```bash
|
|
561
|
+
crm backlink set-status <id> --status non_crawlable --note "Enlace dentro de documento Issuu — hotspot JS, no rastreable"
|
|
562
|
+
crm backlink set-status <id> --status active --note "Verificado: <a> dofollow real cargado por JS (SPA); el fetch http no lo veía"
|
|
563
|
+
crm backlink set-status <id> --status manual_override --note "Parqueado: …" # 'manual_override' detiene el cron
|
|
564
|
+
```
|
|
565
|
+
|
|
566
|
+
If the registered source URL is simply wrong (points at a profile sub-tab that doesn't carry the link, but a sibling page does), fix the URL instead of overriding the status — the cron then re-validates the right page:
|
|
567
|
+
|
|
568
|
+
```bash
|
|
569
|
+
crm backlink update <id> --source-url "https://host/correct-page"
|
|
570
|
+
```
|
|
571
|
+
|
|
572
|
+
To sanity-check the crawler against an independent oracle, `crm backlink reconcile --domain <id>` cross-checks our suspect rows (removed/broken/blocked/non_crawlable) against Ahrefs and flags disagreements for review — it never changes a status. It is **credit-safe**: dry-run by default (shows remaining Ahrefs units + what it would query); add `--confirm` to spend units on ONE filtered call that aborts if the budget is below `--unit-floor` (default 1500). Then fix confirmed mismatches with `set-status` / `update --source-url`.
|
|
573
|
+
|
|
574
|
+
The cron now auto-classifies flipbook/document hosts (Issuu, Calameo, Yumpu reader, Scribd) as `non_crawlable` — their link is a per-page JS hotspot, not a crawlable `<a href>`, so it's neither `removed` nor a live followable link. For SPA/UA-403 hosts the health check falls back to a real headless render before declaring a link dead. Use `set-status` only when you've verified the live page yourself and the automation still disagrees.
|
|
575
|
+
|
|
576
|
+
## Perfiles sociales (`crm social`)
|
|
577
|
+
|
|
578
|
+
Los handles sociales de cada dominio (y los de marca global del cliente) viven en una tabla propia. Léelos antes de redactar contenido social o de proponer diversificación de enlaces — saber qué cuentas existen evita inventar handles.
|
|
579
|
+
|
|
580
|
+
```bash
|
|
581
|
+
crm social list --domain dom_xyz # perfiles de un sitio
|
|
582
|
+
crm social list --client cli_abc # + handles de marca sin dominio
|
|
583
|
+
crm social create --domain dom_xyz --platform instagram --handle growbarato \
|
|
584
|
+
--url https://instagram.com/growbarato --primary
|
|
585
|
+
crm social create --client cli_abc --platform other --label Crunchbase \
|
|
586
|
+
--url https://www.crunchbase.com/organization/growbarato
|
|
587
|
+
crm social update soc_123 --notes "Cuenta oficial verificada"
|
|
588
|
+
crm social delete soc_123 # archiva (borrado suave, restaurable)
|
|
589
|
+
```
|
|
590
|
+
|
|
591
|
+
Reglas: indica `--domain` (perfil del sitio) **o** `--client` (handle de marca sin sitio concreto). `platform` es un catálogo cerrado (`instagram | facebook | x | youtube | tiktok | linkedin | pinterest | threads | trustpilot | other`); `other` exige `--label`. El handle se normaliza quitando la `@`. `--internal-notes` queda staff-only (no se muestra al cliente). Scope `social:write` — staff-only.
|
|
592
|
+
|
|
593
|
+
## Bulk approve / reject your queue
|
|
594
|
+
|
|
595
|
+
`crm review` supports bulk operations via stdin (NDJSON or `kind:id` tokens, ≤100 per call):
|
|
596
|
+
|
|
597
|
+
```bash
|
|
598
|
+
# Approve every pending proposal from your key. The CLI's mini-jq only
|
|
599
|
+
# walks paths — it doesn't support `|` or string interpolation — so use
|
|
600
|
+
# real `jq` after `--quiet` for the projection:
|
|
601
|
+
crm review list --mine --quiet \
|
|
602
|
+
| jq -r '[.tasks[]|"task:"+.id, .comments[]|"comment:"+.id, .edits[]|"edit:"+.id] | .[]' \
|
|
603
|
+
| crm review bulk-approve
|
|
604
|
+
|
|
605
|
+
# Reject many with one reason (allowRetry defaults to true):
|
|
606
|
+
printf 'task:tsk_a\ntask:tsk_b\n' | crm review bulk-reject --reason "Out of scope this quarter"
|
|
607
|
+
```
|
|
608
|
+
|
|
609
|
+
## Escape hatches
|
|
610
|
+
|
|
611
|
+
- `crm commands` — dumps the full CLI surface as JSON (`{ data: { tree, flat } }`). Use this for catalog introspection without parsing `--help`. `SURFACE.txt` in this package is the grep-able mirror.
|
|
612
|
+
- `crm doctor --json` — always safe; doesn't mutate anything. Also forces a fresh npm registry check.
|
|
613
|
+
- `crm auth whoami` — what identity am I acting under? Check this first if attribution looks wrong in the UI.
|
|
614
|
+
|
|
615
|
+
## Update notifications
|
|
616
|
+
|
|
617
|
+
Two channels surface a stale CLI version, both shown via stderr (never on stdout — they don't break `--quiet` pipes):
|
|
618
|
+
|
|
619
|
+
- **Cache nudge**: `[crm] hay una versión nueva: X (tienes Y)`. Printed at startup when `~/.config/crm/cache.json` says a newer version exists on npm. The cache auto-refreshes in a detached background child every 24h on any CLI invocation — `crm doctor` is the explicit refresh path.
|
|
620
|
+
- **Server nudge**: when the API stamps `meta.cliUpdate` on the envelope (caller's `X-Crm-Cli-Version` header is behind the server's `RECOMMENDED_CLI_VERSION` / `MIN_CLI_VERSION`). `"soft"` = friendly upgrade hint; `"required"` = louder `ATENCIÓN` block warning the API surface may have moved. Dedupes once per process.
|
|
621
|
+
|
|
622
|
+
Both are non-blocking — they print and continue. If your agent runs in `--quiet` / pipeline mode and you need to suppress stderr, redirect explicitly (`2>/dev/null`) but you'll lose error messages too.
|