@formant/formant-cli 0.4.5 → 0.5.0

package/README.md

@@ -171,7 +171,7 @@ The CLI will automatically load credentials from your `.env` file.
 ## Quick Start
 
 ```bash
-# View your organization
+# View your organization (add --toon for compact output, --json for machine-readable)
 fcli org get
 
 # List devices with data
@@ -468,6 +468,7 @@ These flags work with any command:
 - `--dev` — Target the dev environment (for testing)
 - `--stage` — Target the stage environment (for staging)
 - `--json` — Output raw JSON instead of formatted tables
+- `--toon` — Output data in TOON (Token-Oriented Object Notation) format
 - `-h, --help` — Show help for any command
 
 **Default environment:** Production (unless `--dev` or `--stage` is specified)
@@ -550,6 +551,60 @@ Use with `jq` for advanced processing:
 fcli device list --json | jq '.items[] | select(.online==true) | .name'
 ```
 
+### TOON
+
+**`--toon` is the recommended output format when working with AI tools, LLM prompts, or any context where token efficiency matters.**
+
+TOON (Token-Oriented Object Notation) is a compact, schema-aware encoding of structured data that is both human-readable and significantly more token-efficient than JSON — making it ideal for pasting into LLM prompts, storing in context windows, and scripting with AI agents.
+
+```bash
+$ fcli org get --toon
+name: Acme Robotics
+id: 6380a48c-0847-4543-a67f-9b7ccc41ec21
+plan: paid
+daysDataRetained: 600
+aiEnabled: true
+investigationsEnabled: true
+flags[19]: settings.role,settings.user,settings.device,...
+billingInfo:
+  usagePrices:
+    devices: 1100
+    dataPoints: 0.00015
+    bytes: 3e-9
+```
+
+```bash
+$ fcli user list --toon
+items[2]{id,email,firstName,lastName,enabled}:
+  4f79f32b-...,alice@acme.io,Alice,Smith,true
+  9a1c22de-...,bob@acme.io,Bob,Jones,true
+```
+
+Key properties of TOON output:
+
+- **Arrays are schema-compressed** — `items[N]{field1,field2,...}:` header followed by rows, rather than repeating field names for every object
+- **Scalars are unquoted** — only strings with special characters are quoted
+- **Nested objects are indented** — structure is preserved but without JSON's punctuation overhead
+- **Null and boolean values are compact** — `null`, `true`, `false` without quotes
+
+**When to use `--toon` vs `--json`:**
+
+| Use case | Recommended flag |
+|---|---|
+| Pasting into an LLM prompt | `--toon` |
+| AI agent / agentic scripting | `--toon` |
+| Shell scripting with `jq` | `--json` |
+| Saving to a file for later processing | `--json` |
+| Quick human inspection | (default) |
+
+```bash
+# Pipe directly into an LLM context or agent prompt
+fcli device list --toon
+fcli event list --severity critical --toon
+fcli investigation runs <id> --toon
+fcli org get --toon
+```
+
 ## Examples
 
 ### Monitor fleet health
@@ -629,6 +684,32 @@ fcli analytics query --sql "SELECT * FROM events WHERE created_at > '2026-01-01'
   --json > analytics_export.json
 ```
 
+### Use with AI tools and LLMs
+
+`--toon` produces compact, token-efficient output that is well-suited for LLM prompts and agentic workflows. Use it anywhere you would otherwise paste JSON into a prompt.
+
+```bash
+# Summarize your fleet for an LLM
+fcli device list --with-data --toon
+
+# Get org context in compact form
+fcli org get --toon
+
+# Pipe investigation results into an AI workflow
+fcli investigation runs <investigation-id> --toon
+
+# Combine with other tools for agentic scripting
+fcli event list --severity critical --limit 20 --toon | your-ai-tool analyze
+
+# Check recent events and device state together
+{
+  echo "=== Critical Events ==="
+  fcli event list --severity critical --limit 10 --toon
+  echo "=== Fleet Status ==="
+  fcli device list --include-offline --toon
+} | your-ai-tool "Summarize what's wrong with my fleet"
+```
+
 ## Development
 
 ### Build from source

package/dist/base-command.d.ts

@@ -12,11 +12,28 @@ export declare abstract class BaseCommand<T extends typeof Command> extends Comm
     static baseFlags: {
         dev: Interfaces.BooleanFlag<boolean>;
         stage: Interfaces.BooleanFlag<boolean>;
+        toon: Interfaces.BooleanFlag<boolean>;
     };
     protected flags: InferredFlags<T>;
     protected args: InferredArgs<T>;
     /** Resolved environment based on --dev / --stage flags. */
     protected get env(): Environment;
+    /** Returns true when --toon flag is active. */
+    toonEnabled(): boolean;
+    /**
+     * Returns true when either --json or --toon is active.
+     * Overriding this ensures human-readable output is suppressed for both flags,
+     * without requiring changes to individual command files.
+     */
+    jsonEnabled(): boolean;
+    /**
+     * Called by oclif when jsonEnabled() is true and run() returns successfully.
+     * When --toon is active, encodes the result as TOON instead of JSON.
+     *
+     * Note: must write to process.stdout directly — this.log() is suppressed
+     * by oclif whenever jsonEnabled() returns true.
+     */
+    protected logJson(json: unknown): void;
     init(): Promise<void>;
     /**
      * Make an authenticated GET/POST request to a Formant API.

package/dist/base-command.js

@@ -1,4 +1,5 @@
 import { Command, Flags } from '@oclif/core';
+import { encode } from '@toon-format/toon';
 import { apiRequest } from './lib/api.js';
 import { login } from './lib/auth.js';
 /**
@@ -18,6 +19,11 @@ export class BaseCommand extends Command {
             exclusive: ['dev'],
             helpGroup: 'GLOBAL',
         }),
+        toon: Flags.boolean({
+            description: 'Output data in TOON (Token-Oriented Object Notation) format',
+            exclusive: ['json'],
+            helpGroup: 'GLOBAL',
+        }),
     };
     flags;
     args;
@@ -29,6 +35,33 @@ export class BaseCommand extends Command {
             return 'stage';
         return 'prod';
     }
+    /** Returns true when --toon flag is active. */
+    toonEnabled() {
+        return Boolean(this.flags?.toon);
+    }
+    /**
+     * Returns true when either --json or --toon is active.
+     * Overriding this ensures human-readable output is suppressed for both flags,
+     * without requiring changes to individual command files.
+     */
+    jsonEnabled() {
+        return super.jsonEnabled() || this.toonEnabled();
+    }
+    /**
+     * Called by oclif when jsonEnabled() is true and run() returns successfully.
+     * When --toon is active, encodes the result as TOON instead of JSON.
+     *
+     * Note: must write to process.stdout directly — this.log() is suppressed
+     * by oclif whenever jsonEnabled() returns true.
+     */
+    logJson(json) {
+        if (this.toonEnabled()) {
+            process.stdout.write(encode(json) + '\n');
+        }
+        else {
+            super.logJson(json);
+        }
+    }
     async init() {
         await super.init();
         const { args, flags } = await this.parse({

package/dist/base-command.js.map

@@ -1 +1 @@
-{"version":3,"file":"base-command.js","sourceRoot":"","sources":["../src/base-command.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,OAAO,EAAE,KAAK,EAAa,MAAM,aAAa,CAAA;AAEtD,OAAO,EAAiB,UAAU,EAAC,MAAM,cAAc,CAAA;AACvD,OAAO,EAAC,KAAK,EAAC,MAAM,eAAe,CAAA;AAQnC;;;GAGG;AACH,MAAM,OAAgB,WAAsC,SAAQ,OAAO;IACzE,MAAM,CAAC,cAAc,GAAG,IAAI,CAAA;IAE5B,MAAM,CAAC,SAAS,GAAG;QACjB,GAAG,EAAE,KAAK,CAAC,OAAO,CAAC;YACjB,WAAW,EAAE,4BAA4B;YACzC,SAAS,EAAE,CAAC,OAAO,CAAC;YACpB,SAAS,EAAE,QAAQ;SACpB,CAAC;QACF,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC;YACnB,WAAW,EAAE,8BAA8B;YAC3C,SAAS,EAAE,CAAC,KAAK,CAAC;YAClB,SAAS,EAAE,QAAQ;SACpB,CAAC;KACH,CAAA;IAES,KAAK,CAAmB;IACxB,IAAI,CAAkB;IAEhC,2DAA2D;IAC3D,IAAc,GAAG;QACf,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG;YAAE,OAAO,KAAK,CAAA;QAChC,IAAI,IAAI,CAAC,KAAK,CAAC,KAAK;YAAE,OAAO,OAAO,CAAA;QACpC,OAAO,MAAM,CAAA;IACf,CAAC;IAEM,KAAK,CAAC,IAAI;QACf,MAAM,KAAK,CAAC,IAAI,EAAE,CAAA;QAClB,MAAM,EAAC,IAAI,EAAE,KAAK,EAAC,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC;YACrC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI;YACpB,SAAS,EAAG,KAAK,CAAC,IAA2B,CAAC,SAAS;YACvD,cAAc,EAAE,IAAI,CAAC,IAAI,CAAC,cAAc;YACxC,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC,KAAK;YACtB,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM;SACzB,CAAC,CAAA;QAEF,IAAI,CAAC,KAAK,GAAG,KAAyB,CAAA;QACtC,IAAI,CAAC,IAAI,GAAG,IAAuB,CAAA;IACrC,CAAC;IAED;;;OAGG;IACO,KAAK,CAAC,GAAG,CACjB,MAAiB,EACjB,IAAY,EACZ,OAAgH;QAEhH,OAAO,UAAU,CAAI,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,CAAA;IACvD,CAAC;IAED;;;OAGG;IACO,KAAK,CAAC,QAAQ;QACtB,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;QAClC,OAAO,IAAI,CAAC,cAAc,CAAA;IAC5B,CAAC;IAEkB,KAAK,CAAC,KAAK,CAAC,GAAgC;QAC7D,MAAM,GAAG,CAAA;IACX,CAAC;IAED;;;OAGG;IACO,iBAAiB,CAAC,OAAe;QACzC,2EAA2E;QAC3E,IAAI,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,KAAK,CAAC,aAAa,CAAC,EAAE,CAAC;YAC1D,OAAO,OAAO,CAAA;QAChB,CAAC;QAED,2DAA2D;QAC3D,OAAO,GAAG,OAAO,YAAY,CAAA;IAC/B,CAAC"}
+{"version":3,"file":"base-command.js","sourceRoot":"","sources":["../src/base-command.ts"],"names":[],"mappings":"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"}

package/dist/help.js

@@ -51,6 +51,7 @@ GLOBAL FLAGS
   --dev            Target the dev environment (for testing)
   --stage          Target the stage environment (for staging)
   --json           Output raw JSON instead of formatted tables
+  --toon           Output data in TOON (Token-Oriented Object Notation) format
   -h, --help       Show help for any command
 
 AUTHENTICATION
@@ -133,6 +134,7 @@ EXAMPLES
 TIPS
   * Use --json with any command to get machine-readable output for scripting
   * Pipe output to jq for advanced JSON processing: fcli device list --json | jq
+  * Use --toon for compact Token-Oriented Object Notation output (great for LLM prompts)
   * Set --dev or --stage to target non-production environments
   * Use fcli <command> --help to see detailed help for any command
 

package/dist/help.js.map

@@ -1 +1 @@
-{"version":3,"file":"help.js","sourceRoot":"","sources":["../src/help.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,IAAI,EAAC,MAAM,aAAa,CAAA;AAEhC,MAAM,CAAC,OAAO,OAAO,QAAS,SAAQ,IAAI;IACrB,KAAK,CAAC,YAAY;QACnC,MAAM,MAAM,GAAG;;kDAE+B,IAAI,CAAC,MAAM,CAAC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyIpE,CAAA;QAEG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;IAClB,CAAC;CACF"}
+{"version":3,"file":"help.js","sourceRoot":"","sources":["../src/help.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,IAAI,EAAC,MAAM,aAAa,CAAA;AAEhC,MAAM,CAAC,OAAO,OAAO,QAAS,SAAQ,IAAI;IACrB,KAAK,CAAC,YAAY;QACnC,MAAM,MAAM,GAAG;;kDAE+B,IAAI,CAAC,MAAM,CAAC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2IpE,CAAA;QAEG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;IAClB,CAAC;CACF"}