@formant/formant-cli 0.2.0 → 0.3.0

package/README.md

@@ -9,21 +9,97 @@
    ╚═╝      ╚═════╝╚══════╝╚═╝
 ```
 
-The official command-line interface for [Formant](https://formant.io) — manage your robot fleet, query telemetry, trigger investigations, and more, all from your terminal.
+**The official command-line interface for [Formant](https://formant.io) — a cloud platform for monitoring, operating, and analyzing robot fleets at scale.**
+
+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.
+
+## What is Formant?
+
+[Formant](https://formant.io) is a cloud observability and operations platform designed specifically for robotics. It provides:
+
+- **Real-time monitoring** — Live telemetry streams (battery, sensors, cameras, logs) from all your robots
+- **Event tracking** — Automatic detection and alerting of critical issues (crashes, errors, anomalies)
+- **AI-powered investigations** — Intelligent root cause analysis that diagnoses problems automatically
+- **Remote operations** — Send commands, trigger actions, and control robots from anywhere
+- **Fleet management** — Organize devices by location, type, or purpose; manage user permissions
+- **Analytics & reporting** — Query historical data with SQL to understand performance trends
 
 ## Features
 
-- 📋 **Device Management** — List, inspect, and configure robots and sensors
-- 📊 **Telemetry Queries** — Retrieve battery, temperature, and sensor data
-- 🔍 **Event Monitoring** — View and filter device events by severity
-- 🤖 **AI Investigations** — Trigger and monitor AI-powered analysis workflows
-- 📡 **Signal Management** — Track and trace investigation signals
-- 💬 **Command Execution** — Send commands to devices
-- 🚨 **Event Triggers** — Configure rules that generate events and signals
-- 👥 **User & Fleet Management** — Manage users, teams, and device groups
-- 📅 **Scheduled Tasks** — Set up recurring jobs and one-time schedules
-- 📈 **Analytics** — Execute SQL queries against analytics data
-- 🗂️ **Key-Value Store** — Manage device metadata
+This CLI provides programmatic access to all Formant capabilities:
+
+### 🤖 Device Management
+- List, create, rename, and delete robots/sensors
+- Add tags for organization (environment, location, customer)
+- View real-time device status and configuration
+- List available telemetry streams
+
+### 📊 Telemetry Queries
+- Query historical sensor data (battery, temperature, position, custom metrics)
+- Retrieve latest values for any stream
+- Filter by time range and device
+- Export data as JSON for analysis
+
+### 📤 Telemetry Ingestion
+- Send numeric, text, JSON, image, video, bitset, and health data to devices
+- Add tags and custom timestamps to telemetry points
+- Batch upload multiple data points in a single request
+- Programmatically populate device streams from scripts and automation
+
+### 🔍 Event Monitoring
+- View events filtered by severity (info, warning, critical, error)
+- Track device online/offline status
+- Investigate alert history for troubleshooting
+- Filter events by device, time range, or type
+
+### 🤖 AI Investigations
+- List available investigation workflows
+- Trigger investigations manually or on-demand
+- View investigation runs, execution logs, and results
+- Get investigation statistics and success rates
+- Trace investigations back to their triggering signals
+
+### 📡 Signal Management
+- List and query signals (investigation triggers)
+- Count signals by type
+- Trace the workflow: Signal → Investigation → Run → Result
+- Understand what triggered each investigation
+
+### 💬 Remote Commands
+- List available command templates for your fleet
+- Send commands to individual devices with parameters
+- View command execution history
+- Check command delivery status
+
+### 🚨 Event Triggers (Automation)
+- View configured trigger rules
+- Understand what conditions create events and signals
+- See trigger configuration (thresholds, exit conditions, device scope)
+
+### 👥 User & Organization Management
+- View organization details (plan, retention, support tier)
+- Update organization name and description
+- List all users and their roles
+- Inspect user permissions and account status
+
+### 🚀 Fleet & Group Management
+- Create logical groups of devices (by location, project, customer)
+- List all fleets and their member devices
+- Organize your fleet for easier management
+
+### 📅 Scheduled Tasks
+- View scheduled investigations and commands
+- Understand recurring workflows and automation
+
+### 📈 Analytics & SQL
+- Execute custom SQL queries against your analytics database
+- List available tables and schemas
+- Analyze fleet performance, uptime, and trends
+
+### 🗂️ Key-Value Metadata Store
+- Store custom metadata per device
+- Retrieve configuration values
+- Update device-specific settings
 
 ## Installation
 
@@ -45,120 +121,258 @@ yarn global add @formant/formant-cli
 pnpm add -g @formant/formant-cli
 ```
 
+After installation, verify it works:
+
+```bash
+fcli --help
+```
+
 ## Authentication
 
-Set your Formant credentials as environment variables:
+Formant CLI uses **service account credentials** for authentication. You'll need to create a service account in your Formant organization first.
+
+### Creating a Service Account
+
+1. Log in to [Formant](https://app.formant.io)
+2. Go to **Settings** → **Users**
+3. Click **Create Service Account**
+4. Copy the generated email and password
+
+### Setting Credentials
+
+Set your credentials as environment variables:
 
 ```bash
-export FORMANT_USER="your-service-account@example.com"
+export FORMANT_USER="your-service-account@org.iam.formant.io"
 export FORMANT_PASSWORD="your-password"
 ```
 
 Or create a `.env` file in your project:
 
 ```env
-FORMANT_USER=your-service-account@example.com
+FORMANT_USER=your-service-account@org.iam.formant.io
 FORMANT_PASSWORD=your-password
 ```
 
+The CLI will automatically load credentials from your `.env` file.
+
 ## Quick Start
 
 ```bash
-# View help
-fcli --help
+# View your organization
+fcli org get
 
-# List all devices in dev environment
+# List all devices
 fcli devices list --dev
 
 # Get device details
 fcli devices get <device-id> --dev
 
-# Query battery telemetry
-fcli query --device <device-id> --stream battery_level --start 2026-01-01 --end 2026-01-02 --dev
+# Query battery telemetry over the last day
+fcli query --device <device-id> --stream battery_level \
+  --start 2026-02-17 --end 2026-02-18 --dev
 
-# View recent events
-fcli events list --device <device-id> --severity critical --limit 20 --dev
+# View recent critical events
+fcli events list --severity critical --limit 20 --dev
 
-# List investigations
+# List all investigations
 fcli investigations list --dev
 
-# Send a command to a device
+# Send a command to a robot
 fcli commands send <device-id> <template-id> --param speed=5 --dev
 ```
 
-## Commands
+## Command Reference
+
+### Organization
+
+Manage your Formant account settings.
+
+```bash
+fcli org get                                   # View organization details
+fcli org update --name "Acme Robotics"         # Update organization name
+fcli org update --description "Production fleet" # Update description
+```
 
 ### Devices
 
-Manage robots and sensors in your fleet.
+Create, list, and manage robots/sensors in your fleet.
 
 ```bash
-fcli devices list [--tag <key>=<value>] [--online] [--dev]
-fcli devices get <device-id> [--dev]
-fcli devices config <device-id> [--dev]
-fcli devices streams <device-id> [--dev]
-fcli devices last-seen <device-id> [--dev]
+# Listing and filtering
+fcli devices list                              # List all devices
+fcli devices list --online                     # Only online devices
+fcli devices list --tag location=warehouse     # Filter by tag
+
+# Device details
+fcli devices get <device-id>                   # Get full device details
+fcli devices config <device-id>                # Get device configuration
+fcli devices streams <device-id>               # List available data streams
+fcli devices last-seen <device-id>             # Get last activity timestamp
+
+# Device management
+fcli devices create --name "robot-001"         # Create a new device
+fcli devices rename <device-id> --name "new-name" # Rename a device
+fcli devices delete <device-id>                # Delete (disable) a device
+
+# Tagging
+fcli devices tag <device-id> --key env --value prod    # Add/update tag
+fcli devices untag <device-id> --key env               # Remove tag
 ```
 
 ### Events
 
-View important events emitted by devices.
+View and filter important events emitted by your devices.
 
 ```bash
-fcli events list [--device <id>] [--severity <level>] [--limit <n>] [--dev]
-fcli events get <event-id> [--dev]
+fcli events list                               # List all recent events
+fcli events list --device <device-id>          # Events for one device
+fcli events list --severity critical           # Filter by severity
+fcli events list --limit 50                    # Limit results
+fcli events list --start 2026-01-01            # Filter by date range
+fcli events get <event-id>                     # Get event details
 ```
 
+**Severity levels:** `info`, `warning`, `error`, `critical`
+
 ### Query
 
-Retrieve telemetry and sensor data from devices.
+Retrieve historical telemetry and sensor data.
 
 ```bash
-fcli query --device <id> --stream <name> --start <date> --end <date> [--dev]
-fcli query latest-values --device <id> --stream <name> [--dev]
+# Historical data
+fcli query --device <device-id> --stream battery_level \
+  --start 2026-01-01 --end 2026-01-02
+
+# Latest values
+fcli query latest-values --device <device-id> --stream battery_level
+
+# Common streams: battery_level, temperature, cpu_usage, memory_usage, location
+```
+
+### Ingest
+
+Send telemetry data to devices via the Formant ingestion API.
+
+```bash
+# Numeric data
+fcli ingest numeric 42.5 --device <device-id> --stream battery_level
+fcli ingest numeric 23.8 --device <device-id> --stream temperature --tag location=warehouse
+
+# Text data
+fcli ingest text "System operational" --device <device-id> --stream status
+fcli ingest text "Low battery warning" --device <device-id> --stream alerts --tag severity=warning
+
+# JSON data
+fcli ingest json '{"x":10,"y":20}' --device <device-id> --stream position
+fcli ingest json '{"speed":15,"heading":90}' --device <device-id> --stream nav_data
+
+# Image data
+fcli ingest image https://example.com/camera.jpg --device <device-id> --stream camera_front
+fcli ingest image https://example.com/image.jpg --device <device-id> --stream camera --size 102400
+
+# Video data
+fcli ingest video https://example.com/recording.mp4 --device <device-id> --stream camera_feed --duration 30000
+fcli ingest video https://cdn.example.com/video.webm --device <device-id> --stream video --duration 15000 --mime-type video/webm
+
+# Bitset data (multiple boolean key-value pairs)
+fcli ingest bitset --device <device-id> --stream sensors \
+  --keys motor_on,door_open,battery_charging \
+  --values true,false,true
+
+# Health status
+fcli ingest health --device <device-id> --stream health_status --status operational
+fcli ingest health --device <device-id> --stream health --status error --clock-skew 1500
+
+# Batch ingestion (multiple items from JSON file or stdin)
+fcli ingest batch --file payload.json
+cat batch.json | fcli ingest batch --stdin
+```
+
+**Common flags for all ingest commands:**
+- `--device <id>` - Target device ID (required)
+- `--stream <name>` - Stream name (required)
+- `--tag key=value` - Add tags as string key-value pairs (repeatable: `--tag env=prod --tag region=us-west`)
+- `--timestamp <ms>` - Unix timestamp in milliseconds (defaults to current time)
+
+**Health status values:** `unknown`, `operational`, `offline`, `error`
+
+**Batch format example** (`payload.json`):
+```json
+{
+  "items": [
+    {
+      "deviceId": "abc-123",
+      "name": "battery_level",
+      "type": "numeric",
+      "tags": {"env": "prod"},
+      "points": [[1642867200000, 42.5]]
+    },
+    {
+      "deviceId": "abc-123",
+      "name": "status",
+      "type": "text",
+      "tags": {"env": "prod"},
+      "points": [[1642867200000, "operational"]]
+    }
+  ]
+}
 ```
 
+**Note:** The `tags` field is optional and contains string key-value pairs only. Use `"tags": {}` if no tags are needed.
+
 ### Investigations
 
-Run and monitor AI-powered analysis workflows.
+Trigger and monitor AI-powered analysis workflows that diagnose device issues.
 
 ```bash
-fcli investigations list [--dev]
-fcli investigations get <investigation-id> [--dev]
-fcli investigations stats [--start <date>] [--end <date>] [--dev]
-fcli investigations runs-list <investigation-id> [--dev]
-fcli investigations run <investigation-id> <run-id> [--trace-signal] [--dev]
-fcli investigations trigger <investigation-id> <device-id> [--dev]
-fcli investigations analytics <investigation-id> [--dev]
+# Listing
+fcli investigations list                       # List all investigations
+fcli investigations get <investigation-id>     # Get investigation details
+
+# Triggering
+fcli investigations trigger <inv-id> <device-id> # Start an investigation
+
+# Runs
+fcli investigations runs <investigation-id>    # List all runs
+fcli investigations run <inv-id> <run-id>      # Get run details & logs
+fcli investigations run <inv-id> <run-id> --trace-signal # Trace back to signal
+
+# Analytics
+fcli investigations stats --start 2026-01-01  # Get metrics
+fcli investigations analytics <investigation-id> # Get investigation analytics
 ```
 
 ### Signals
 
-Manage signals (points of interest that trigger analysis).
+Signals are points of interest (from events, schedules, or manual triggers) that start investigations.
 
 ```bash
-fcli signals list [--start <date>] [--end <date>] [--dev]
+fcli signals list                              # List all signals
+fcli signals query --start 2026-01-01 --end 2026-02-01 # Query by time
+fcli signals count                             # Count signals by type
+fcli signals get <signal-id>                   # Get signal details
 ```
 
 ### Commands
 
-Manage command templates and send commands to devices.
+Send remote commands to devices and view execution history.
 
 ```bash
-fcli commands list [--dev]
-fcli commands get <command-id> [--dev]
-fcli commands for-device <device-id> [--dev]
-fcli commands send <device-id> <template-id> [--param <key>=<value>] [--dev]
-fcli commands history <device-id> [--dev]
+fcli commands list                             # List all command templates
+fcli commands get <command-id>                 # Get template details
+fcli commands for-device <device-id>           # Commands available for device
+fcli commands send <device-id> <template-id> --param key=value # Send command
+fcli commands history <device-id>              # View command history
 ```
 
 ### Event Triggers
 
-Manage event trigger rules that generate events and signals.
+View automated trigger rules that generate events and signals based on device conditions.
 
 ```bash
-fcli event-triggers list [--dev]
-fcli event-triggers get <trigger-id> [--dev]
+fcli event-triggers list                       # List all trigger rules
+fcli event-triggers get <trigger-id>           # Get trigger configuration
 ```
 
 ### Users
@@ -166,117 +380,163 @@ fcli event-triggers get <trigger-id> [--dev]
 Manage users in your organization.
 
 ```bash
-fcli users list [--dev]
-fcli users get <user-id> [--dev]
+fcli users list                                # List all users
+fcli users get <user-id>                       # Get user details
 ```
 
 ### Fleets
 
-Manage device groups (fleets).
+Organize devices into logical groups (by location, type, project, customer).
 
 ```bash
-fcli fleets list [--dev]
-fcli fleets get <fleet-id> [--dev]
+fcli fleets list                               # List all fleets
+fcli fleets get <fleet-id>                     # Get fleet details
 ```
 
 ### Schedules
 
-Manage scheduled tasks and recurring jobs.
+View recurring tasks and one-time scheduled jobs.
 
 ```bash
-fcli schedules list [--dev]
-fcli schedules get <schedule-id> [--dev]
+fcli schedules list                            # List all schedules
+fcli schedules get <schedule-id>               # Get schedule details
 ```
 
 ### Analytics
 
-Execute SQL queries against analytics data.
+Execute custom SQL queries against your Formant analytics database.
 
 ```bash
-fcli analytics query --sql "<query>" [--dev]
-fcli analytics tables [--dev]
+fcli analytics tables                          # List available tables
+fcli analytics query --sql "SELECT * FROM events WHERE severity='critical' LIMIT 10"
 ```
 
 ### Key-Value Store
 
-Manage key-value store for device metadata.
+Store and retrieve custom metadata for devices.
 
 ```bash
-fcli kv list <device-id> [--dev]
-fcli kv get <device-id> <key> [--dev]
-fcli kv set <device-id> <key> <value> [--dev]
+fcli kv list <device-id>                       # List all keys
+fcli kv get <device-id> <key>                  # Get value
+fcli kv set <device-id> <key> <value>          # Set value
 ```
 
 ## Global Flags
 
-- `--dev` — Target the dev environment
-- `--stage` — Target the stage environment
-- `--json` — Format output as JSON
-- `-h, --help` — Show help for a command
+These flags work with any command:
 
-## Environment Variables
+- `--dev` — Target the dev environment (for testing)
+- `--stage` — Target the stage environment (for staging)  
+- `--json` — Output raw JSON instead of formatted tables
+- `-h, --help` — Show help for any command
 
-| Variable | Description | Required |
-|----------|-------------|----------|
-| `FORMANT_USER` | Service account email | Yes |
-| `FORMANT_PASSWORD` | Service account password | Yes |
+**Default environment:** Production (unless `--dev` or `--stage` is specified)
 
-## Examples
+## Output Formats
+
+### Table (default)
 
-### List online devices with specific tag
+Human-readable tables optimized for terminal viewing:
 
 ```bash
-fcli devices list --tag location=warehouse --online --dev
+$ fcli devices list --dev
+
+Devices (dev):
+
+NAME              ID                                      STATUS   TAGS
+────────────────────────────────────────────────────────────────────────
+robot-001         a1b2c3d4-...                            online   env=prod, location=warehouse
+robot-002         e5f6g7h8-...                            offline  env=dev
 ```
 
-### Query telemetry data over a time range
+### JSON
+
+Machine-readable JSON for scripting and automation:
 
 ```bash
-fcli query --device abc123 --stream battery_level \
-  --start 2026-01-01 --end 2026-01-02 --dev --json
+$ fcli devices list --dev --json
+{
+  "items": [
+    {
+      "id": "a1b2c3d4-...",
+      "name": "robot-001",
+      "online": true,
+      "tags": {
+        "env": "prod",
+        "location": "warehouse"
+      }
+    }
+  ]
+}
 ```
 
-### Trace an investigation back to its signal
+Use with `jq` for advanced processing:
 
 ```bash
-# Get investigation run
-fcli investigations run <investigation-id> <run-id> --trace-signal --dev
-
-# Get the signal details
-fcli signals get <signal-id> --dev
+fcli devices list --json | jq '.items[] | select(.online==true) | .name'
 ```
 
-### Monitor critical events
+## Examples
+
+### Monitor fleet health
 
 ```bash
-fcli events list --severity critical --limit 50 --dev
+# Check which devices are offline
+fcli devices list --json | jq '.items[] | select(.online==false) | .name'
+
+# View recent critical events across the fleet
+fcli events list --severity critical --limit 50
+
+# Check battery levels
+for device in $(fcli devices list --json | jq -r '.items[].id'); do
+  echo "Device: $device"
+  fcli query latest-values --device $device --stream battery_level
+done
 ```
 
-### Send a command with parameters
+### Investigate a device issue
 
 ```bash
-fcli commands send device-123 template-456 \
-  --param speed=10 \
-  --param direction=forward \
-  --dev
-```
+# 1. View recent events for the device
+fcli events list --device <device-id> --limit 20
 
-## Output Formats
+# 2. Check what investigations have run
+fcli investigations runs <investigation-id>
 
-### Table (default)
+# 3. Get detailed logs for a specific run
+fcli investigations run <inv-id> <run-id>
+
+# 4. Query relevant telemetry
+fcli query --device <device-id> --stream temperature \
+  --start 2026-02-17T10:00:00Z --end 2026-02-17T12:00:00Z
+```
 
-Human-readable tables for terminal viewing:
+### Automate fleet operations
 
 ```bash
-fcli devices list --dev
+# Tag all production devices
+for device in $(fcli devices list --json | jq -r '.items[].id'); do
+  fcli devices tag $device --key environment --value production
+done
+
+# Send command to all devices in a fleet
+for device in $(fcli fleets get <fleet-id> --json | jq -r '.devices[].id'); do
+  fcli commands send $device <template-id> --param mode=standby
+done
 ```
 
-### JSON
-
-Machine-readable JSON for scripting and automation:
+### Export data for analysis
 
 ```bash
-fcli devices list --dev --json | jq '.items[] | .name'
+# Export all critical events to JSON
+fcli events list --severity critical --limit 1000 --json > critical_events.json
+
+# Export device list with tags
+fcli devices list --json | jq '.items[] | {name, id, tags}' > devices.json
+
+# Query analytics and save results
+fcli analytics query --sql "SELECT * FROM events WHERE created_at > '2026-01-01'" \
+  --json > analytics_export.json
 ```
 
 ## Development
@@ -296,27 +556,31 @@ npm run build
 npm run dev -- devices list --dev
 ```
 
-### Build and pack
+### Run directly
 
 ```bash
-npm run prepack
+./bin/run.js --help
 ```
 
 ## Requirements
 
-- Node.js >= 18.0.0
-- A Formant service account with appropriate permissions
+- **Node.js** >= 18.0.0
+- A **Formant account** with service account credentials
+- Appropriate **permissions** for the operations you want to perform
 
-## Support
+## Support & Resources
 
-- Documentation: [https://formant.io/docs](https://formant.io/docs)
-- Support: [support@formant.io](mailto:support@formant.io)
-- Issues: [https://github.com/FormantIO/formant-cli/issues](https://github.com/FormantIO/formant-cli/issues)
+- **Documentation:** [https://formant.io/docs](https://formant.io/docs)
+- **Support Email:** [support@formant.io](mailto:support@formant.io)
+- **GitHub Issues:** [https://github.com/FormantIO/formant-cli/issues](https://github.com/FormantIO/formant-cli/issues)
+- **Formant Platform:** [https://app.formant.io](https://app.formant.io)
 
 ## License
 
 UNLICENSED — Proprietary software for Formant customers.
 
+See [LICENSE](./LICENSE) for details.
+
 ---
 
 Made with ⚡ by [Formant](https://formant.io)