@formo/cli 1.0.2 → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Formo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -10,6 +10,23 @@ npm install -g @formo/cli
 npx @formo/cli
 ```
 
+## Install the Formo Analytics agent skill
+
+This repository also ships the [`formo-analytics`](skills/formo-analytics/SKILL.md) skill for Claude Code, Codex, and other [Agent Skills](https://agentskills.io)-compatible tools. It teaches agents to use Formo's MCP server, CLI, and REST API for project-scoped product and onchain analytics.
+
+Install it in the current project:
+
+```bash
+npx skills add https://github.com/getformo/cli/tree/main/skills/formo-analytics
+```
+
+Or install it globally for Claude Code and Codex:
+
+```bash
+npx skills add getformo/cli --skill formo-analytics --global \
+  --agent claude-code --agent codex
+```
+
 ## Authentication
 
 Save your API key locally:
@@ -24,7 +41,7 @@ Or set the `FORMO_API_KEY` environment variable — it takes precedence over the
 export FORMO_API_KEY=formo_abc123
 ```
 
-Get your API key from `Settings → API Keys` in the [Formo dashboard](https://app.formo.so).
+Get your API key from `Settings → API` in the [Formo dashboard](https://app.formo.so).
 
 For local development or proxying, override API hosts with:
 
@@ -191,7 +208,7 @@ Get a single alert by ID.
 
 ```bash
 formo alerts create --name "High value tx" --trigger-type event \
-  --trigger-filters '[{"name":"event","operator":"equals","value":"transaction"}]' \
+  --trigger-filters '[{"name":"event","operator":"eq","value":"transaction"}]' \
   --recipient '[{"type":"email","value":["alerts@myapp.com"]}]'
 ```
 
@@ -384,7 +401,7 @@ Pre-built analytics pipes — the same data that powers the Formo dashboard —
 |---|---|
 | `--date-from` | Inclusive start date `YYYY-MM-DD` (default: 7 days before `--date-to`) |
 | `--date-to` | Inclusive end date `YYYY-MM-DD` (default: today) |
-| `--filters` | JSON array of `[{field,op,value}]`. Use `in`/`notIn` with a pipe-delimited value (e.g. `"chrome\|firefox"`) |
+| `--filters` | JSON array of `[{field,op,value}]`. Use `in`/`nin` with a pipe-delimited value (e.g. `"chrome\|firefox"`) |
 | `--params` | JSON object of pipe-specific params merged into the query (e.g. `{"limit":10,"group_by":"device"}`) |
 
 ```bash
@@ -392,7 +409,7 @@ formo analytics kpis
 formo analytics kpis --date-from 2026-04-01 --date-to 2026-04-30 --params '{"group_by":"device"}'
 formo analytics funnel --date-from 2026-04-01 --date-to 2026-04-30 --params '{"steps":[{"type":"event","event":"page","name":"page::0","filters":[]},{"type":"track","event":"connect","name":"connect::1","filters":[]}],"window_seconds":86400}'
 formo analytics top_wallets --date-from 2026-04-01 --date-to 2026-04-30 --params '{"limit":10}'
-formo analytics retention --filters '[{"field":"location","op":"equals","value":"US"}]'
+formo analytics retention --filters '[{"field":"location","op":"eq","value":"US"}]'
 ```
 
 > Requires `query:read` scope. Run `formo analytics <pipe> --help` for the pipe-specific params accepted via `--params`.
@@ -448,7 +465,7 @@ formo events ingest --event '{"type":"track","channel":"cli","version":"1","anon
 | Field | Type | Description |
 |---|---|---|
 | `field` | `string` | Typed path (see prefixes below) |
-| `op` | `string` | `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `in`, `nin` |
+| `op` | `string` | `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`, `contains` (social fields only), `notEmpty` / `isEmpty` (value-less existence checks). Long-form spellings (`equals`, `greater`, `includes`, …) are retired — the API rejects them with a `400` naming the token |
 | `value` | `any` | Value to compare against |
 | `scope` | `string` | _(token filters only)_ `any` or `protocol` |
 | `appId` | `string` | _(token filters with `scope: protocol`)_ e.g. `aave-v3` |

package/dist/commands/analytics.js

@@ -15,7 +15,7 @@ exports.analytics = incur_1.Cli.create('analytics', {
 const PIPES = [
     { name: 'kpis', description: 'Traffic KPIs: visitors, pageviews, bounce rate, session duration' },
     { name: 'event_timeseries', description: 'Event counts over time' },
-    { name: 'funnel', description: 'Conversion funnel across ordered steps. --params: steps (JSON array of {type,event,name,filters?}), window_seconds, funnel_type, breakdown' },
+    { name: 'funnel', description: 'Conversion funnel across ordered steps. --params: steps (JSON array of {type,event,name,filters?}), window_seconds, funnel_type, group_by, limit, attribution' },
     { name: 'flow', description: 'User path/flow analysis. --params: start_step / end_step (JSON {type,event,...}), global_filters, window_seconds, max_steps' },
     { name: 'frequency', description: 'Engagement frequency distribution' },
     { name: 'lifecycle', description: 'User lifecycle stages (new, returning, power, resurrected, churned)' },
@@ -123,7 +123,7 @@ const sharedOptions = incur_1.z.object({
         .string()
         .optional()
         .describe('JSON array of filter conditions: [{"field","op","value"}]. ' +
-        'Use op "in"/"notIn" with a pipe-delimited value (e.g. "chrome|firefox").'),
+        'Use op "in"/"nin" with a pipe-delimited value (e.g. "chrome|firefox").'),
     params: incur_1.z
         .string()
         .optional()

package/dist/commands/profiles.js

@@ -230,7 +230,9 @@ exports.profiles.command('search', {
             'Chains: chains.balance or chains.{chain_id}.balance. ' +
             'Apps: apps.{app_id}.balance. Tokens: tokens.{address}.balance ' +
             '(optional "scope":"any"|"protocol" + "appId"). Labels: labels.{tag_id}. ' +
-            'op: eq, neq, gt, gte, lt, lte, in, nin.'),
+            'op: eq, neq, gt, gte, lt, lte, in, nin, contains, notEmpty, isEmpty ' +
+            '(contains = substring, social fields only; notEmpty/isEmpty = value-less existence checks on string fields). ' +
+            'Long-form spellings (equals, notEquals, greater, greaterOrEqual, less, lessOrEqual, notIn, includes) are retired; the API rejects them with a 400 naming the token.'),
         logic: incur_1.z
             .enum(['and', 'or'])
             .optional()

package/dist/index.js

@@ -23,7 +23,7 @@ function loginGuide() {
         ui_1.color.boldGreen("How to get your API key:"),
         "",
         `  ${ui_1.color.white("1.")} Go to ${ui_1.color.cyan(DASHBOARD_URL)}`,
-        `  ${ui_1.color.white("2.")} Navigate to ${ui_1.color.bold("Settings")} → ${ui_1.color.bold("API Keys")}`,
+        `  ${ui_1.color.white("2.")} Navigate to ${ui_1.color.bold("Settings")} → ${ui_1.color.bold("API")}`,
         `  ${ui_1.color.white("3.")} Click ${ui_1.color.bold('"Create API Key"')} and copy the key`,
         `  ${ui_1.color.white("4.")} Run:`,
         "",

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@formo/cli",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "packageManager": "pnpm@11.1.2",
   "description": "Formo API CLI — query profiles and analytics data",
+  "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/getformo/cli.git"
@@ -29,7 +30,7 @@
     "test:watch": "mocha --watch"
   },
   "dependencies": {
-    "axios": "^1.15.2",
+    "axios": "^1.18.0",
     "incur": "^0.3.4"
   },
   "overrides": {