@formant/formant-cli 0.3.1 → 0.4.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (182) hide show
  1. package/README.md +193 -142
  2. package/dist/commands/{commands → command}/for-device.js +2 -2
  3. package/dist/commands/command/for-device.js.map +1 -0
  4. package/dist/commands/{commands → command}/get.js +2 -2
  5. package/dist/commands/command/get.js.map +1 -0
  6. package/dist/commands/{commands → command}/history.js +3 -3
  7. package/dist/commands/command/history.js.map +1 -0
  8. package/dist/commands/{commands → command}/list.js +2 -2
  9. package/dist/commands/command/list.js.map +1 -0
  10. package/dist/commands/{commands → command}/send.js +5 -5
  11. package/dist/commands/command/send.js.map +1 -0
  12. package/dist/commands/{devices → device}/config.js +2 -2
  13. package/dist/commands/device/config.js.map +1 -0
  14. package/dist/commands/{devices → device}/create.js +3 -3
  15. package/dist/commands/device/create.js.map +1 -0
  16. package/dist/commands/{devices → device}/delete.js +2 -2
  17. package/dist/commands/device/delete.js.map +1 -0
  18. package/dist/commands/{devices → device}/get.js +2 -2
  19. package/dist/commands/device/get.js.map +1 -0
  20. package/dist/commands/{devices → device}/list.d.ts +7 -1
  21. package/dist/commands/{devices → device}/list.js +67 -13
  22. package/dist/commands/device/list.js.map +1 -0
  23. package/dist/commands/{devices → device}/rename.js +2 -2
  24. package/dist/commands/device/rename.js.map +1 -0
  25. package/dist/commands/{devices → device}/streams.d.ts +1 -0
  26. package/dist/commands/device/streams.js +155 -0
  27. package/dist/commands/device/streams.js.map +1 -0
  28. package/dist/commands/{devices → device}/tag.js +3 -3
  29. package/dist/commands/device/tag.js.map +1 -0
  30. package/dist/commands/{devices → device}/untag.js +3 -3
  31. package/dist/commands/device/untag.js.map +1 -0
  32. package/dist/commands/{events → event}/get.js +2 -2
  33. package/dist/commands/event/get.js.map +1 -0
  34. package/dist/commands/{events → event}/list.js +4 -4
  35. package/dist/commands/event/list.js.map +1 -0
  36. package/dist/commands/{event-triggers → event-trigger}/get.js +2 -2
  37. package/dist/commands/event-trigger/get.js.map +1 -0
  38. package/dist/commands/{event-triggers → event-trigger}/list.js +2 -2
  39. package/dist/commands/event-trigger/list.js.map +1 -0
  40. package/dist/commands/{fleets → fleet}/get.js +2 -2
  41. package/dist/commands/fleet/get.js.map +1 -0
  42. package/dist/commands/{fleets → fleet}/list.js +2 -2
  43. package/dist/commands/fleet/list.js.map +1 -0
  44. package/dist/commands/{investigations → investigation}/analytics.js +3 -3
  45. package/dist/commands/investigation/analytics.js.map +1 -0
  46. package/dist/commands/{investigations → investigation}/get.js +2 -2
  47. package/dist/commands/investigation/get.js.map +1 -0
  48. package/dist/commands/{investigations → investigation}/list.js +3 -3
  49. package/dist/commands/investigation/list.js.map +1 -0
  50. package/dist/commands/{investigations → investigation}/run.js +3 -3
  51. package/dist/commands/investigation/run.js.map +1 -0
  52. package/dist/commands/{investigations → investigation}/runs-list.js +3 -3
  53. package/dist/commands/investigation/runs-list.js.map +1 -0
  54. package/dist/commands/{investigations → investigation}/runs.js +2 -2
  55. package/dist/commands/investigation/runs.js.map +1 -0
  56. package/dist/commands/{investigations → investigation}/stats.js +2 -2
  57. package/dist/commands/investigation/stats.js.map +1 -0
  58. package/dist/commands/{investigations → investigation}/trigger.js +2 -2
  59. package/dist/commands/investigation/trigger.js.map +1 -0
  60. package/dist/commands/persona/delegate-task.d.ts +14 -0
  61. package/dist/commands/persona/delegate-task.js +50 -0
  62. package/dist/commands/persona/delegate-task.js.map +1 -0
  63. package/dist/commands/persona/get.d.ts +10 -0
  64. package/dist/commands/persona/get.js +98 -0
  65. package/dist/commands/persona/get.js.map +1 -0
  66. package/dist/commands/{signals → persona}/list.d.ts +1 -1
  67. package/dist/commands/persona/list.js +31 -0
  68. package/dist/commands/persona/list.js.map +1 -0
  69. package/dist/commands/persona/task-status.d.ts +12 -0
  70. package/dist/commands/persona/task-status.js +57 -0
  71. package/dist/commands/persona/task-status.js.map +1 -0
  72. package/dist/commands/{schedules → schedule}/get.js +2 -2
  73. package/dist/commands/schedule/get.js.map +1 -0
  74. package/dist/commands/{schedules → schedule}/list.js +2 -2
  75. package/dist/commands/schedule/list.js.map +1 -0
  76. package/dist/commands/{signals → signal}/count.js +3 -3
  77. package/dist/commands/signal/count.js.map +1 -0
  78. package/dist/commands/signal/create.d.ts +16 -0
  79. package/dist/commands/signal/create.js +95 -0
  80. package/dist/commands/signal/create.js.map +1 -0
  81. package/dist/commands/{signals → signal}/get.js +3 -3
  82. package/dist/commands/signal/get.js.map +1 -0
  83. package/dist/commands/signal/list.d.ts +12 -0
  84. package/dist/commands/signal/list.js +85 -0
  85. package/dist/commands/signal/list.js.map +1 -0
  86. package/dist/commands/{signals → signal}/query.d.ts +1 -0
  87. package/dist/commands/signal/query.js +100 -0
  88. package/dist/commands/signal/query.js.map +1 -0
  89. package/dist/commands/signal/set-ground-truth.d.ts +12 -0
  90. package/dist/commands/signal/set-ground-truth.js +46 -0
  91. package/dist/commands/signal/set-ground-truth.js.map +1 -0
  92. package/dist/commands/{users → user}/get.js +2 -2
  93. package/dist/commands/user/get.js.map +1 -0
  94. package/dist/commands/{users → user}/list.js +2 -2
  95. package/dist/commands/user/list.js.map +1 -0
  96. package/dist/help.js +53 -47
  97. package/dist/help.js.map +1 -1
  98. package/dist/lib/api.d.ts +1 -1
  99. package/dist/lib/api.js +3 -0
  100. package/dist/lib/api.js.map +1 -1
  101. package/dist/lib/config.d.ts +1 -0
  102. package/dist/lib/config.js +3 -0
  103. package/dist/lib/config.js.map +1 -1
  104. package/dist/lib/presence.d.ts +46 -0
  105. package/dist/lib/presence.js +95 -0
  106. package/dist/lib/presence.js.map +1 -0
  107. package/oclif.manifest.json +1192 -790
  108. package/package.json +28 -25
  109. package/dist/commands/commands/for-device.js.map +0 -1
  110. package/dist/commands/commands/get.js.map +0 -1
  111. package/dist/commands/commands/history.js.map +0 -1
  112. package/dist/commands/commands/list.js.map +0 -1
  113. package/dist/commands/commands/send.js.map +0 -1
  114. package/dist/commands/devices/config.js.map +0 -1
  115. package/dist/commands/devices/create.js.map +0 -1
  116. package/dist/commands/devices/delete.js.map +0 -1
  117. package/dist/commands/devices/get.js.map +0 -1
  118. package/dist/commands/devices/last-seen.d.ts +0 -10
  119. package/dist/commands/devices/last-seen.js +0 -25
  120. package/dist/commands/devices/last-seen.js.map +0 -1
  121. package/dist/commands/devices/list.js.map +0 -1
  122. package/dist/commands/devices/rename.js.map +0 -1
  123. package/dist/commands/devices/streams.js +0 -100
  124. package/dist/commands/devices/streams.js.map +0 -1
  125. package/dist/commands/devices/tag.js.map +0 -1
  126. package/dist/commands/devices/untag.js.map +0 -1
  127. package/dist/commands/event-triggers/get.js.map +0 -1
  128. package/dist/commands/event-triggers/list.js.map +0 -1
  129. package/dist/commands/events/get.js.map +0 -1
  130. package/dist/commands/events/list.js.map +0 -1
  131. package/dist/commands/fleets/get.js.map +0 -1
  132. package/dist/commands/fleets/list.js.map +0 -1
  133. package/dist/commands/investigations/analytics.js.map +0 -1
  134. package/dist/commands/investigations/get.js.map +0 -1
  135. package/dist/commands/investigations/list.js.map +0 -1
  136. package/dist/commands/investigations/run.js.map +0 -1
  137. package/dist/commands/investigations/runs-list.js.map +0 -1
  138. package/dist/commands/investigations/runs.js.map +0 -1
  139. package/dist/commands/investigations/stats.js.map +0 -1
  140. package/dist/commands/investigations/trigger.js.map +0 -1
  141. package/dist/commands/schedules/get.js.map +0 -1
  142. package/dist/commands/schedules/list.js.map +0 -1
  143. package/dist/commands/signals/count.js.map +0 -1
  144. package/dist/commands/signals/get.js.map +0 -1
  145. package/dist/commands/signals/list.js +0 -30
  146. package/dist/commands/signals/list.js.map +0 -1
  147. package/dist/commands/signals/query.js +0 -52
  148. package/dist/commands/signals/query.js.map +0 -1
  149. package/dist/commands/users/get.js.map +0 -1
  150. package/dist/commands/users/list.js.map +0 -1
  151. /package/dist/commands/{commands → command}/for-device.d.ts +0 -0
  152. /package/dist/commands/{commands → command}/get.d.ts +0 -0
  153. /package/dist/commands/{commands → command}/history.d.ts +0 -0
  154. /package/dist/commands/{commands → command}/list.d.ts +0 -0
  155. /package/dist/commands/{commands → command}/send.d.ts +0 -0
  156. /package/dist/commands/{devices → device}/config.d.ts +0 -0
  157. /package/dist/commands/{devices → device}/create.d.ts +0 -0
  158. /package/dist/commands/{devices → device}/delete.d.ts +0 -0
  159. /package/dist/commands/{devices → device}/get.d.ts +0 -0
  160. /package/dist/commands/{devices → device}/rename.d.ts +0 -0
  161. /package/dist/commands/{devices → device}/tag.d.ts +0 -0
  162. /package/dist/commands/{devices → device}/untag.d.ts +0 -0
  163. /package/dist/commands/{events → event}/get.d.ts +0 -0
  164. /package/dist/commands/{events → event}/list.d.ts +0 -0
  165. /package/dist/commands/{event-triggers → event-trigger}/get.d.ts +0 -0
  166. /package/dist/commands/{event-triggers → event-trigger}/list.d.ts +0 -0
  167. /package/dist/commands/{fleets → fleet}/get.d.ts +0 -0
  168. /package/dist/commands/{fleets → fleet}/list.d.ts +0 -0
  169. /package/dist/commands/{investigations → investigation}/analytics.d.ts +0 -0
  170. /package/dist/commands/{investigations → investigation}/get.d.ts +0 -0
  171. /package/dist/commands/{investigations → investigation}/list.d.ts +0 -0
  172. /package/dist/commands/{investigations → investigation}/run.d.ts +0 -0
  173. /package/dist/commands/{investigations → investigation}/runs-list.d.ts +0 -0
  174. /package/dist/commands/{investigations → investigation}/runs.d.ts +0 -0
  175. /package/dist/commands/{investigations → investigation}/stats.d.ts +0 -0
  176. /package/dist/commands/{investigations → investigation}/trigger.d.ts +0 -0
  177. /package/dist/commands/{schedules → schedule}/get.d.ts +0 -0
  178. /package/dist/commands/{schedules → schedule}/list.d.ts +0 -0
  179. /package/dist/commands/{signals → signal}/count.d.ts +0 -0
  180. /package/dist/commands/{signals → signal}/get.d.ts +0 -0
  181. /package/dist/commands/{users → user}/get.d.ts +0 -0
  182. /package/dist/commands/{users → user}/list.d.ts +0 -0
package/README.md CHANGED
@@ -2,16 +2,16 @@
2
2
 
3
3
  ```
4
4
  ███████╗ ██████╗██╗ ██╗
5
- ██╔════╝██╔════╝██║ ██║ 🤖 Formant CLI
6
- █████╗ ██║ ██║ ██║ Manage your robot fleet
7
- ██╔══╝ ██║ ██║ ██║ 🚀 from the command line
5
+ ██╔════╝██╔════╝██║ ██║ Formant CLI
6
+ █████╗ ██║ ██║ ██║ Manage your robot fleet
7
+ ██╔══╝ ██║ ██║ ██║ from the command line
8
8
  ██║ ╚██████╗███████╗██║
9
9
  ╚═╝ ╚═════╝╚══════╝╚═╝
10
10
  ```
11
11
 
12
12
  **The official command-line interface for [Formant](https://formant.io) — a cloud platform for monitoring, operating, and analyzing robot fleets at scale.**
13
13
 
14
- Formant helps robotics teams observe, troubleshoot, and control their robots in production. With `fcli`, you can manage your entire fleet from the terminal: query telemetry, trigger AI-powered investigations, send remote commands, manage users and permissions, and automate workflows.
14
+ Formant helps robotics teams observe, troubleshoot, and control their robots in production. With `fcli`, you can manage your entire fleet from the terminal: query telemetry, trigger AI-powered investigations, delegate tasks to AI personas, send remote commands, manage users and permissions, and automate workflows.
15
15
 
16
16
  ## What is Formant?
17
17
 
@@ -20,6 +20,7 @@ Formant helps robotics teams observe, troubleshoot, and control their robots in
20
20
  - **Real-time monitoring** — Live telemetry streams (battery, sensors, cameras, logs) from all your robots
21
21
  - **Event tracking** — Automatic detection and alerting of critical issues (crashes, errors, anomalies)
22
22
  - **AI-powered investigations** — Intelligent root cause analysis that diagnoses problems automatically
23
+ - **AI personas** — Configurable AI agents with tools for async task delegation
23
24
  - **Remote operations** — Send commands, trigger actions, and control robots from anywhere
24
25
  - **Fleet management** — Organize devices by location, type, or purpose; manage user permissions
25
26
  - **Analytics & reporting** — Query historical data with SQL to understand performance trends
@@ -28,75 +29,85 @@ Formant helps robotics teams observe, troubleshoot, and control their robots in
28
29
 
29
30
  This CLI provides programmatic access to all Formant capabilities:
30
31
 
31
- ### 🤖 Device Management
32
+ ### Device Management
32
33
  - List, create, rename, and delete robots/sensors
33
34
  - Add tags for organization (environment, location, customer)
34
35
  - View real-time device status and configuration
35
- - List available telemetry streams
36
+ - List available telemetry streams with per-stream data presence (datapoint counts, last seen, freshness)
37
+ - Data-based last seen timestamps and datapoint counts on device listings
38
+ - Filter to devices that have ingested data (`--with-data`)
36
39
 
37
- ### 📊 Telemetry Queries
40
+ ### Telemetry Queries
38
41
  - Query historical sensor data (battery, temperature, position, custom metrics)
39
42
  - Retrieve latest values for any stream
40
43
  - Filter by time range and device
41
44
  - Export data as JSON for analysis
42
45
 
43
- ### 📤 Telemetry Ingestion
46
+ ### Telemetry Ingestion
44
47
  - Send numeric, text, JSON, image, video, bitset, and health data to devices
45
48
  - Add tags and custom timestamps to telemetry points
46
49
  - Batch upload multiple data points in a single request
47
50
  - Programmatically populate device streams from scripts and automation
48
51
 
49
- ### 🔍 Event Monitoring
52
+ ### Event Monitoring
50
53
  - View events filtered by severity (info, warning, critical, error)
51
54
  - Track device online/offline status
52
55
  - Investigate alert history for troubleshooting
53
56
  - Filter events by device, time range, or type
54
57
 
55
- ### 🤖 AI Investigations
58
+ ### AI Personas
59
+ - List available AI personas and their configurations
60
+ - View persona details including integrations and available tools
61
+ - Delegate async tasks to personas (fire-and-forget)
62
+ - Check task status and results
63
+
64
+ ### AI Investigations
56
65
  - List available investigation workflows
57
- - Trigger investigations manually or on-demand
66
+ - Trigger investigations manually with custom input
58
67
  - View investigation runs, execution logs, and results
59
68
  - Get investigation statistics and success rates
60
69
  - Trace investigations back to their triggering signals
61
70
 
62
- ### 📡 Signal Management
71
+ ### Signal Management & Ground Truth
72
+ - Create manual signals for testing and evaluation
63
73
  - List and query signals (investigation triggers)
74
+ - Assign ground truth (expected outcomes) to signals for evaluation
75
+ - View signals with their ground truth annotations
64
76
  - Count signals by type
65
- - Trace the workflow: Signal Investigation Run Result
66
- - Understand what triggered each investigation
77
+ - Trace the workflow: Signal -> Investigation -> Run -> Result
67
78
 
68
- ### 💬 Remote Commands
79
+ ### Remote Commands
69
80
  - List available command templates for your fleet
70
81
  - Send commands to individual devices with parameters
71
82
  - View command execution history
72
83
  - Check command delivery status
73
84
 
74
- ### 🚨 Event Triggers (Automation)
85
+ ### Event Triggers (Automation)
75
86
  - View configured trigger rules
76
87
  - Understand what conditions create events and signals
77
88
  - See trigger configuration (thresholds, exit conditions, device scope)
78
89
 
79
- ### 👥 User & Organization Management
90
+ ### User & Organization Management
80
91
  - View organization details (plan, retention, support tier)
81
92
  - Update organization name and description
82
93
  - List all users and their roles
83
94
  - Inspect user permissions and account status
84
95
 
85
- ### 🚀 Fleet & Group Management
96
+ ### Fleet & Group Management
86
97
  - Create logical groups of devices (by location, project, customer)
87
98
  - List all fleets and their member devices
88
99
  - Organize your fleet for easier management
89
100
 
90
- ### 📅 Scheduled Tasks
101
+ ### Scheduled Tasks
91
102
  - View scheduled investigations and commands
92
103
  - Understand recurring workflows and automation
93
104
 
94
- ### 📈 Analytics & SQL
105
+ ### Analytics & SQL
95
106
  - Execute custom SQL queries against your analytics database
96
107
  - List available tables and schemas
97
108
  - Analyze fleet performance, uptime, and trends
98
109
 
99
- ### 🗂️ Key-Value Metadata Store
110
+ ### Key-Value Metadata Store
100
111
  - Store custom metadata per device
101
112
  - Retrieve configuration values
102
113
  - Update device-specific settings
@@ -134,7 +145,7 @@ Formant CLI uses **service account credentials** for authentication. You'll need
134
145
  ### Creating a Service Account
135
146
 
136
147
  1. Log in to [Formant](https://app.formant.io)
137
- 2. Go to **Settings** **Users**
148
+ 2. Go to **Settings** -> **Users**
138
149
  3. Click **Create Service Account**
139
150
  4. Copy the generated email and password
140
151
 
@@ -162,24 +173,29 @@ The CLI will automatically load credentials from your `.env` file.
162
173
  # View your organization
163
174
  fcli org get
164
175
 
165
- # List all devices
166
- fcli devices list --dev
176
+ # List devices with data
177
+ fcli device list --with-data --dev
167
178
 
168
179
  # Get device details
169
- fcli devices get <device-id> --dev
180
+ fcli device get <device-id> --dev
170
181
 
171
182
  # Query battery telemetry over the last day
172
183
  fcli query --device <device-id> --stream battery_level \
173
184
  --start 2026-02-17 --end 2026-02-18 --dev
174
185
 
175
186
  # View recent critical events
176
- fcli events list --severity critical --limit 20 --dev
187
+ fcli event list --severity critical --limit 20 --dev
188
+
189
+ # List AI personas and delegate a task
190
+ fcli persona list --dev
191
+ fcli persona delegate-task <persona-id> "Analyze recent device failures" --dev
192
+ fcli persona task-status <task-id> --dev
177
193
 
178
194
  # List all investigations
179
- fcli investigations list --dev
195
+ fcli investigation list --dev
180
196
 
181
197
  # Send a command to a robot
182
- fcli commands send <device-id> <template-id> --param speed=5 --dev
198
+ fcli command send <device-id> <template-id> --param speed=5 --dev
183
199
  ```
184
200
 
185
201
  ## Command Reference
@@ -194,43 +210,48 @@ fcli org update --name "Acme Robotics" # Update organization name
194
210
  fcli org update --description "Production fleet" # Update description
195
211
  ```
196
212
 
197
- ### Devices
213
+ ### Device
198
214
 
199
215
  Create, list, and manage robots/sensors in your fleet.
200
216
 
201
217
  ```bash
202
218
  # Listing and filtering
203
- fcli devices list # List all devices
204
- fcli devices list --online # Only online devices
205
- fcli devices list --tag location=warehouse # Filter by tag
219
+ fcli device list # Online devices (default)
220
+ fcli device list --include-offline # Include offline devices
221
+ fcli device list --with-data # Only devices with ingested data
222
+ fcli device list --with-data --days 90 # Widen the search window (default: 30d)
223
+ fcli device list --tag location=warehouse # Filter by tag
206
224
 
207
225
  # Device details
208
- fcli devices get <device-id> # Get full device details
209
- fcli devices config <device-id> # Get device configuration
210
- fcli devices streams <device-id> # List available data streams
211
- fcli devices last-seen <device-id> # Get last activity timestamp
226
+ fcli device get <device-id> # Get full device details
227
+ fcli device config <device-id> # Get device configuration
228
+
229
+ # Stream discovery with data presence
230
+ fcli device streams <device-id> # List streams with datapoint counts,
231
+ # last seen (ISO), and freshness
232
+ fcli device streams <device-id> --days 30 # Adjust presence lookback (default: 7d)
212
233
 
213
234
  # Device management
214
- fcli devices create --name "robot-001" # Create a new device
215
- fcli devices rename <device-id> --name "new-name" # Rename a device
216
- fcli devices delete <device-id> # Delete (disable) a device
235
+ fcli device create --name "robot-001" # Create a new device
236
+ fcli device rename <device-id> --name "new-name" # Rename a device
237
+ fcli device delete <device-id> # Delete (disable) a device
217
238
 
218
239
  # Tagging
219
- fcli devices tag <device-id> --key env --value prod # Add/update tag
220
- fcli devices untag <device-id> --key env # Remove tag
240
+ fcli device tag <device-id> --key env --value prod # Add/update tag
241
+ fcli device untag <device-id> --key env # Remove tag
221
242
  ```
222
243
 
223
- ### Events
244
+ ### Event
224
245
 
225
246
  View and filter important events emitted by your devices.
226
247
 
227
248
  ```bash
228
- fcli events list # List all recent events
229
- fcli events list --device <device-id> # Events for one device
230
- fcli events list --severity critical # Filter by severity
231
- fcli events list --limit 50 # Limit results
232
- fcli events list --start 2026-01-01 # Filter by date range
233
- fcli events get <event-id> # Get event details
249
+ fcli event list # List all recent events
250
+ fcli event list --device <device-id> # Events for one device
251
+ fcli event list --severity critical # Filter by severity
252
+ fcli event list --limit 50 # Limit results
253
+ fcli event list --start 2026-01-01 # Filter by date range
254
+ fcli event get <event-id> # Get event details
234
255
  ```
235
256
 
236
257
  **Severity levels:** `info`, `warning`, `error`, `critical`
@@ -265,15 +286,12 @@ fcli ingest text "Low battery warning" --device <device-id> --stream alerts --ta
265
286
 
266
287
  # JSON data
267
288
  fcli ingest json '{"x":10,"y":20}' --device <device-id> --stream position
268
- fcli ingest json '{"speed":15,"heading":90}' --device <device-id> --stream nav_data
269
289
 
270
290
  # Image data
271
291
  fcli ingest image https://example.com/camera.jpg --device <device-id> --stream camera_front
272
- fcli ingest image https://example.com/image.jpg --device <device-id> --stream camera --size 102400
273
292
 
274
293
  # Video data
275
294
  fcli ingest video https://example.com/recording.mp4 --device <device-id> --stream camera_feed --duration 30000
276
- fcli ingest video https://cdn.example.com/video.webm --device <device-id> --stream video --duration 15000 --mime-type video/webm
277
295
 
278
296
  # Bitset data (multiple boolean key-value pairs)
279
297
  fcli ingest bitset --device <device-id> --stream sensors \
@@ -282,7 +300,6 @@ fcli ingest bitset --device <device-id> --stream sensors \
282
300
 
283
301
  # Health status
284
302
  fcli ingest health --device <device-id> --stream health_status --status operational
285
- fcli ingest health --device <device-id> --stream health --status error --clock-skew 1500
286
303
 
287
304
  # Batch ingestion (multiple items from JSON file or stdin)
288
305
  fcli ingest batch --file payload.json
@@ -292,114 +309,119 @@ cat batch.json | fcli ingest batch --stdin
292
309
  **Common flags for all ingest commands:**
293
310
  - `--device <id>` - Target device ID (required)
294
311
  - `--stream <name>` - Stream name (required)
295
- - `--tag key=value` - Add tags as string key-value pairs (repeatable: `--tag env=prod --tag region=us-west`)
312
+ - `--tag key=value` - Add tags as string key-value pairs (repeatable)
296
313
  - `--timestamp <ms>` - Unix timestamp in milliseconds (defaults to current time)
297
314
 
298
315
  **Health status values:** `unknown`, `operational`, `offline`, `error`
299
316
 
300
- **Batch format example** (`payload.json`):
301
- ```json
302
- {
303
- "items": [
304
- {
305
- "deviceId": "abc-123",
306
- "name": "battery_level",
307
- "type": "numeric",
308
- "tags": {"env": "prod"},
309
- "points": [[1642867200000, 42.5]]
310
- },
311
- {
312
- "deviceId": "abc-123",
313
- "name": "status",
314
- "type": "text",
315
- "tags": {"env": "prod"},
316
- "points": [[1642867200000, "operational"]]
317
- }
318
- ]
319
- }
317
+ ### Persona
318
+
319
+ Manage AI personas and delegate async tasks.
320
+
321
+ ```bash
322
+ # Listing and details
323
+ fcli persona list # List all personas
324
+ fcli persona get <persona-id> # View persona details and tools
325
+
326
+ # Async task delegation
327
+ fcli persona delegate-task <persona-id> "Analyze recent device failures"
328
+ fcli persona delegate-task <persona-id> "Generate a daily report" --name "Daily Report"
329
+ fcli persona task-status <task-id> # Check task status and results
320
330
  ```
321
331
 
322
- **Note:** The `tags` field is optional and contains string key-value pairs only. Use `"tags": {}` if no tags are needed.
332
+ The `delegate-task` command creates a task, assigns it to the persona, and queues it for
333
+ async execution. It returns immediately with a task ID. Use `task-status` to check progress.
323
334
 
324
- ### Investigations
335
+ ### Investigation
325
336
 
326
337
  Trigger and monitor AI-powered analysis workflows that diagnose device issues.
327
338
 
328
339
  ```bash
329
340
  # Listing
330
- fcli investigations list # List all investigations
331
- fcli investigations get <investigation-id> # Get investigation details
341
+ fcli investigation list # List all investigations
342
+ fcli investigation get <investigation-id> # Get investigation details
332
343
 
333
344
  # Triggering
334
- fcli investigations trigger <inv-id> <device-id> # Start an investigation
345
+ fcli investigation trigger <id> --input "Robot stopped responding"
335
346
 
336
347
  # Runs
337
- fcli investigations runs <investigation-id> # List all runs
338
- fcli investigations run <inv-id> <run-id> # Get run details & logs
339
- fcli investigations run <inv-id> <run-id> --trace-signal # Trace back to signal
348
+ fcli investigation runs <investigation-id> # List all runs
349
+ fcli investigation run <inv-id> <run-id> # Get run details & logs
340
350
 
341
351
  # Analytics
342
- fcli investigations stats --start 2026-01-01 # Get metrics
343
- fcli investigations analytics <investigation-id> # Get investigation analytics
352
+ fcli investigation stats --start 2026-01-01 # Get metrics
353
+ fcli investigation analytics <investigation-id> # Get investigation analytics
344
354
  ```
345
355
 
346
- ### Signals
356
+ ### Signal
347
357
 
348
358
  Signals are points of interest (from events, schedules, or manual triggers) that start investigations.
359
+ You can create signals manually and assign ground truth (expected outcomes) for evaluation.
349
360
 
350
361
  ```bash
351
- fcli signals list # List all signals
352
- fcli signals query --start 2026-01-01 --end 2026-02-01 # Query by time
353
- fcli signals count # Count signals by type
354
- fcli signals get <signal-id> # Get signal details
362
+ # Listing and querying
363
+ fcli signal list # List all signals
364
+ fcli signal list --investigation <inv-id> # List with ground truth annotations
365
+ fcli signal query --start 2026-01-01 --end 2026-02-01 # Query by time
366
+ fcli signal count # Count signals by type
367
+ fcli signal get <signal-id> # Get signal details
368
+
369
+ # Creating signals
370
+ fcli signal create "Motor overheated on device X"
371
+ fcli signal create "Sensor fault" --device <device-id>
372
+ fcli signal create "Test scenario" --investigation <inv-id> \
373
+ --ground-truth "Should detect thermal issue"
374
+
375
+ # Ground truth (expected outcomes for evaluation)
376
+ fcli signal set-ground-truth <signal-id> <investigation-id> "Expected outcome text"
355
377
  ```
356
378
 
357
- ### Commands
379
+ ### Command
358
380
 
359
381
  Send remote commands to devices and view execution history.
360
382
 
361
383
  ```bash
362
- fcli commands list # List all command templates
363
- fcli commands get <command-id> # Get template details
364
- fcli commands for-device <device-id> # Commands available for device
365
- fcli commands send <device-id> <template-id> --param key=value # Send command
366
- fcli commands history <device-id> # View command history
384
+ fcli command list # List all command templates
385
+ fcli command get <command-id> # Get template details
386
+ fcli command for-device <device-id> # Commands available for device
387
+ fcli command send <device-id> <template-id> --param key=value # Send command
388
+ fcli command history <device-id> # View command history
367
389
  ```
368
390
 
369
- ### Event Triggers
391
+ ### Event Trigger
370
392
 
371
393
  View automated trigger rules that generate events and signals based on device conditions.
372
394
 
373
395
  ```bash
374
- fcli event-triggers list # List all trigger rules
375
- fcli event-triggers get <trigger-id> # Get trigger configuration
396
+ fcli event-trigger list # List all trigger rules
397
+ fcli event-trigger get <trigger-id> # Get trigger configuration
376
398
  ```
377
399
 
378
- ### Users
400
+ ### User
379
401
 
380
402
  Manage users in your organization.
381
403
 
382
404
  ```bash
383
- fcli users list # List all users
384
- fcli users get <user-id> # Get user details
405
+ fcli user list # List all users
406
+ fcli user get <user-id> # Get user details
385
407
  ```
386
408
 
387
- ### Fleets
409
+ ### Fleet
388
410
 
389
411
  Organize devices into logical groups (by location, type, project, customer).
390
412
 
391
413
  ```bash
392
- fcli fleets list # List all fleets
393
- fcli fleets get <fleet-id> # Get fleet details
414
+ fcli fleet list # List all fleets
415
+ fcli fleet get <fleet-id> # Get fleet details
394
416
  ```
395
417
 
396
- ### Schedules
418
+ ### Schedule
397
419
 
398
420
  View recurring tasks and one-time scheduled jobs.
399
421
 
400
422
  ```bash
401
- fcli schedules list # List all schedules
402
- fcli schedules get <schedule-id> # Get schedule details
423
+ fcli schedule list # List all schedules
424
+ fcli schedule get <schedule-id> # Get schedule details
403
425
  ```
404
426
 
405
427
  ### Analytics
@@ -426,7 +448,7 @@ fcli kv set <device-id> <key> <value> # Set value
426
448
  These flags work with any command:
427
449
 
428
450
  - `--dev` — Target the dev environment (for testing)
429
- - `--stage` — Target the stage environment (for staging)
451
+ - `--stage` — Target the stage environment (for staging)
430
452
  - `--json` — Output raw JSON instead of formatted tables
431
453
  - `-h, --help` — Show help for any command
432
454
 
@@ -439,14 +461,29 @@ These flags work with any command:
439
461
  Human-readable tables optimized for terminal viewing:
440
462
 
441
463
  ```bash
442
- $ fcli devices list --dev
464
+ $ fcli device list --with-data --dev
443
465
 
444
- Devices (dev):
466
+ Devices — with data (dev):
445
467
 
446
- NAME ID STATUS TAGS
447
- ────────────────────────────────────────────────────────────────────────
448
- robot-001 a1b2c3d4-... online env=prod, location=warehouse
449
- robot-002 e5f6g7h8-... offline env=dev
468
+ NAME ID ONLINE TYPE LAST SEEN (30D) DATAPOINTS (30D)
469
+ ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
470
+ carter.1 a8840212-a0a4-4d0b-8a47-098563894748 false default 2026-02-19T19:05:37.536Z 720156
471
+ DJI Matrice 4E 10f78fd5-c00d-42d9-94c4-b310646f59be false default 2026-02-18T01:17:41.167Z 917051
472
+ ```
473
+
474
+ ```bash
475
+ $ fcli device streams <device-id> --dev
476
+
477
+ Device Streams (dev):
478
+
479
+ Device: Walt (020e59a1-...)
480
+ Configured: 10 | Discovered from data: 34
481
+ Presence (last 7d): 0 active, 32 recent, 0 stale, 0 dormant, 12 no data
482
+
483
+ NAME TYPE SOURCE DATAPOINTS LAST SEEN FRESHNESS
484
+ spot.robot_state.battery numeric data 20195 2026-02-19T23:37:01.281Z recent
485
+ spot.localization text data 16962 2026-02-19T23:37:01.271Z recent
486
+ spot.hand.image custom config — — —
450
487
  ```
451
488
 
452
489
  ### JSON
@@ -454,17 +491,15 @@ robot-002 e5f6g7h8-... offline env=dev
454
491
  Machine-readable JSON for scripting and automation:
455
492
 
456
493
  ```bash
457
- $ fcli devices list --dev --json
494
+ $ fcli device list --with-data --dev --json
458
495
  {
459
496
  "items": [
460
497
  {
461
- "id": "a1b2c3d4-...",
462
- "name": "robot-001",
463
- "online": true,
464
- "tags": {
465
- "env": "prod",
466
- "location": "warehouse"
467
- }
498
+ "id": "a8840212-...",
499
+ "name": "carter.1",
500
+ "online": false,
501
+ "last_seen": "2026-02-19T19:05:37.536Z",
502
+ "datapoints": 720156
468
503
  }
469
504
  ]
470
505
  }
@@ -473,7 +508,7 @@ $ fcli devices list --dev --json
473
508
  Use with `jq` for advanced processing:
474
509
 
475
510
  ```bash
476
- fcli devices list --json | jq '.items[] | select(.online==true) | .name'
511
+ fcli device list --json | jq '.items[] | select(.online==true) | .name'
477
512
  ```
478
513
 
479
514
  ## Examples
@@ -481,30 +516,46 @@ fcli devices list --json | jq '.items[] | select(.online==true) | .name'
481
516
  ### Monitor fleet health
482
517
 
483
518
  ```bash
519
+ # Find devices that have data
520
+ fcli device list --with-data
521
+
522
+ # Find devices with data, wider search window
523
+ fcli device list --with-data --days 90
524
+
484
525
  # Check which devices are offline
485
- fcli devices list --json | jq '.items[] | select(.online==false) | .name'
526
+ fcli device list --include-offline --json | jq '.items[] | select(.online==false) | .name'
486
527
 
487
528
  # View recent critical events across the fleet
488
- fcli events list --severity critical --limit 50
529
+ fcli event list --severity critical --limit 50
489
530
 
490
- # Check battery levels
491
- for device in $(fcli devices list --json | jq -r '.items[].id'); do
492
- echo "Device: $device"
493
- fcli query latest-values --device $device --stream battery_level
494
- done
531
+ # Discover what streams a device has and their data freshness
532
+ fcli device streams <device-id>
533
+ ```
534
+
535
+ ### Delegate a task to an AI persona
536
+
537
+ ```bash
538
+ # List available personas
539
+ fcli persona list
540
+
541
+ # Delegate an async task
542
+ fcli persona delegate-task <persona-id> "Check all offline devices and summarize issues"
543
+
544
+ # Check the result
545
+ fcli persona task-status <task-id>
495
546
  ```
496
547
 
497
548
  ### Investigate a device issue
498
549
 
499
550
  ```bash
500
551
  # 1. View recent events for the device
501
- fcli events list --device <device-id> --limit 20
552
+ fcli event list --device <device-id> --limit 20
502
553
 
503
- # 2. Check what investigations have run
504
- fcli investigations runs <investigation-id>
554
+ # 2. Trigger an investigation
555
+ fcli investigation trigger <investigation-id> --input "Device stopped responding"
505
556
 
506
- # 3. Get detailed logs for a specific run
507
- fcli investigations run <inv-id> <run-id>
557
+ # 3. Check investigation runs
558
+ fcli investigation runs <investigation-id>
508
559
 
509
560
  # 4. Query relevant telemetry
510
561
  fcli query --device <device-id> --stream temperature \
@@ -515,13 +566,13 @@ fcli query --device <device-id> --stream temperature \
515
566
 
516
567
  ```bash
517
568
  # Tag all production devices
518
- for device in $(fcli devices list --json | jq -r '.items[].id'); do
519
- fcli devices tag $device --key environment --value production
569
+ for device in $(fcli device list --json | jq -r '.items[].id'); do
570
+ fcli device tag $device --key environment --value production
520
571
  done
521
572
 
522
573
  # Send command to all devices in a fleet
523
- for device in $(fcli fleets get <fleet-id> --json | jq -r '.devices[].id'); do
524
- fcli commands send $device <template-id> --param mode=standby
574
+ for device in $(fcli fleet get <fleet-id> --json | jq -r '.devices[].id'); do
575
+ fcli command send $device <template-id> --param mode=standby
525
576
  done
526
577
  ```
527
578
 
@@ -529,10 +580,10 @@ done
529
580
 
530
581
  ```bash
531
582
  # Export all critical events to JSON
532
- fcli events list --severity critical --limit 1000 --json > critical_events.json
583
+ fcli event list --severity critical --limit 1000 --json > critical_events.json
533
584
 
534
585
  # Export device list with tags
535
- fcli devices list --json | jq '.items[] | {name, id, tags}' > devices.json
586
+ fcli device list --json | jq '.items[] | {name, id, tags}' > devices.json
536
587
 
537
588
  # Query analytics and save results
538
589
  fcli analytics query --sql "SELECT * FROM events WHERE created_at > '2026-01-01'" \
@@ -553,7 +604,7 @@ npm run build
553
604
  ### Run in development mode
554
605
 
555
606
  ```bash
556
- npm run dev -- devices list --dev
607
+ npm run dev -- device list --dev
557
608
  ```
558
609
 
559
610
  ### Run directly
@@ -583,4 +634,4 @@ See [LICENSE](./LICENSE) for details.
583
634
 
584
635
  ---
585
636
 
586
- Made with by [Formant](https://formant.io)
637
+ Made with care by [Formant](https://formant.io)
@@ -10,8 +10,8 @@ export default class CommandsForDevice extends BaseCommand {
10
10
  Returns commands that match the device's tags and filters. Only enabled commands
11
11
  that apply to this device are shown.`;
12
12
  static examples = [
13
- '<%= config.bin %> commands for-device <device-id>',
14
- '<%= config.bin %> commands for-device <device-id> --json',
13
+ '<%= config.bin %> command for-device <device-id>',
14
+ '<%= config.bin %> command for-device <device-id> --json',
15
15
  ];
16
16
  static summary = 'List commands available for a device';
17
17
  async run() {
@@ -0,0 +1 @@
1
+ {"version":3,"file":"for-device.js","sourceRoot":"","sources":["../../../src/commands/command/for-device.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,IAAI,EAAC,MAAM,aAAa,CAAA;AAEhC,OAAO,EAAC,WAAW,EAAC,MAAM,uBAAuB,CAAA;AACjD,OAAO,EAAc,WAAW,EAAC,MAAM,yBAAyB,CAAA;AAEhE,MAAM,CAAC,OAAO,OAAO,iBAAkB,SAAQ,WAAqC;IAClF,MAAM,CAAU,IAAI,GAAG;QACrB,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,EAAC,WAAW,EAAE,kBAAkB,EAAE,QAAQ,EAAE,IAAI,EAAC,CAAC;KACzE,CAAA;IAED,MAAM,CAAU,WAAW,GAAG;;;qCAGK,CAAA;IAEnC,MAAM,CAAU,QAAQ,GAAG;QACzB,kDAAkD;QAClD,yDAAyD;KAC1D,CAAA;IAED,MAAM,CAAU,OAAO,GAAG,sCAAsC,CAAA;IAEzD,KAAK,CAAC,GAAG;QACd,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,GAAG,CAC3B,OAAO,EACP,WAAW,IAAI,CAAC,IAAI,CAAC,QAAQ,WAAW,EACxC,EAAC,MAAM,EAAE,KAAK,EAAC,CAChB,CAAA;QAED,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,CAAC;YACxB,MAAM,OAAO,GAAa;gBACxB,EAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,EAAC;gBACvC,EAAC,GAAG,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,EAAC;gBAC7C,EAAC,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,EAAC;gBACnC,EAAC,GAAG,EAAE,aAAa,EAAE,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,EAAE,EAAC;aACtD,CAAA;YAED,IAAI,CAAC,GAAG,CAAC,oCAAoC,IAAI,CAAC,GAAG,MAAM,CAAC,CAAA;YAC5D,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,MAAM,CAAC,KAAK,IAAI,EAAE,EAAE,OAAO,CAAC,CAAC,CAAA;YAClD,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;QACd,CAAC;QAED,OAAO,MAAM,CAAA;IACf,CAAC"}
@@ -11,8 +11,8 @@ Shows the full template configuration including command string, parameter schema
11
11
  device targeting filters, and delivery settings. If the template has structured
12
12
  parameters (schema), they are displayed in a readable format.`;
13
13
  static examples = [
14
- '<%= config.bin %> commands get <template-id>',
15
- '<%= config.bin %> commands get <template-id> --json',
14
+ '<%= config.bin %> command get <template-id>',
15
+ '<%= config.bin %> command get <template-id> --json',
16
16
  ];
17
17
  static summary = 'Get command template details';
18
18
  async run() {