@formo/cli 0.2.0 → 1.0.0

package/README.md

@@ -82,18 +82,19 @@ Search wallet profiles with filters, sorting, and pagination. Returns a `Paginat
 | `--address` | Filter by wallet address |
 | `--page` | Page number (1-indexed, default `1`) |
 | `--size` | Page size (default `100`, max `1000`) |
-| `--orderBy` | `last_onchain`, `first_onchain`, `net_worth_usd`, `updated_at`, `tx_count`, `first_seen`, `last_seen`, `num_sessions`, `revenue`, `volume`, `points` |
-| `--orderDir` | `asc` or `desc` |
+| `--order-by` | `last_onchain`, `first_onchain`, `net_worth_usd`, `updated_at`, `tx_count`, `first_seen`, `last_seen`, `num_sessions`, `revenue`, `volume`, `points` |
+| `--order-dir` | `asc` or `desc` |
 | `--expand` | Comma-separated fields to expand |
 | `--conditions` | JSON array of `FilterCondition` objects (see below) |
 | `--logic` | Combine conditions with `and` (default) or `or` |
 
 ```bash
 formo profiles search --size 10
-formo profiles search --orderBy net_worth_usd --orderDir desc --size 5
+formo profiles search --order-by net_worth_usd --order-dir desc --size 5
 formo profiles search --page 2 --size 20
-formo profiles search --conditions '[{"field":"net_worth_usd","op":"gt","value":10000}]' --size 20
-formo profiles search --conditions '[{"field":"net_worth_usd","op":"gt","value":10000},{"field":"tx_count","op":"gt","value":50}]' --logic or --size 20
+formo profiles search --conditions '[{"field":"users.net_worth_usd","op":"gt","value":10000}]' --size 20
+formo profiles search --conditions '[{"field":"users.net_worth_usd","op":"gt","value":10000},{"field":"users.volume","op":"gt","value":1000}]' --logic or --size 20
+formo profiles search --conditions '[{"field":"chains.1.balance","op":"gt","value":1000}]' --size 20
 ```
 
 ### `profiles update <address>`
@@ -115,18 +116,18 @@ formo profiles update vitalik.eth --properties '{"email":"alice@example.com"}'
 
 ### `profiles labels create <address>`
 
-Upsert one or more labels on a wallet profile. Provide either a single label via `--tagId` or a batch via `--labels`.
+Upsert one or more labels on a wallet profile. Provide either a single label via `--tag-id` or a batch via `--labels`.
 
 | Option | Description |
 |---|---|
-| `--tagId` | Label identifier (e.g. `vip`, `airdrop_eligible`) |
+| `--tag-id` | Label identifier (e.g. `vip`, `airdrop_eligible`) |
 | `--value` | Optional label value (e.g. tier name, country code) |
-| `--chainId` | Optional chain identifier the label applies to |
+| `--chain-id` | Optional chain identifier the label applies to |
 | `--labels` | JSON array of `UserLabelInput` objects for batch upsert |
 
 ```bash
-formo profiles labels create 0xd8dA... --tagId vip
-formo profiles labels create 0xd8dA... --tagId tier --value gold --chainId 1
+formo profiles labels create 0xd8dA... --tag-id vip
+formo profiles labels create 0xd8dA... --tag-id tier --value gold --chain-id 1
 formo profiles labels create 0xd8dA... --labels '[{"tag_id":"vip"},{"tag_id":"airdrop_eligible","chain_id":"1"}]'
 ```
 
@@ -136,12 +137,12 @@ Delete a label from a wallet profile.
 
 | Option | Description |
 |---|---|
-| `--tagId` | Label identifier to delete (required) |
-| `--chainId` | Optional chain identifier to scope the deletion |
+| `--tag-id` | Label identifier to delete (required) |
+| `--chain-id` | Optional chain identifier to scope the deletion |
 
 ```bash
-formo profiles labels delete 0xd8dA... --tagId vip
-formo profiles labels delete 0xd8dA... --tagId tier --chainId 1
+formo profiles labels delete 0xd8dA... --tag-id vip
+formo profiles labels delete 0xd8dA... --tag-id tier --chain-id 1
 ```
 
 > Requires `profiles:write` scope.
@@ -163,14 +164,14 @@ Get a single alert by ID.
 | Option | Description |
 |---|---|
 | `--name` | Alert name |
-| `--triggerType` | Trigger type (e.g. `event`, `threshold`) |
-| `--triggerFilters` | JSON array of trigger filter objects |
+| `--trigger-type` | Trigger type (e.g. `event`, `threshold`) |
+| `--trigger-filters` | JSON array of trigger filter objects |
 | `--recipient` | JSON array of recipient objects |
 | `--secret` | Webhook secret |
 
 ```bash
-formo alerts create --name "High value tx" --triggerType event \
-  --triggerFilters '[{"name":"event","operator":"equals","value":"transaction"}]' \
+formo alerts create --name "High value tx" --trigger-type event \
+  --trigger-filters '[{"name":"event","operator":"equals","value":"transaction"}]' \
   --recipient '[{"type":"email","value":["alerts@myapp.com"]}]'
 ```
 
@@ -226,19 +227,19 @@ Delete a board.
 
 Chart commands. Charts live inside a board. Requires `charts:read` / `charts:write`.
 
-### `charts list --boardId <boardId>`
+### `charts list --board-id <boardId>`
 List all charts in a board.
 
-### `charts get <chartId> --boardId <boardId>`
+### `charts get <chartId> --board-id <boardId>`
 Get a single chart by ID.
 
-### `charts create --boardId <boardId> --body '<json>'`
+### `charts create --board-id <boardId> --body '<json>'`
 Create a chart from a JSON config string.
 
-### `charts update <chartId> --boardId <boardId> --body '<json>'`
+### `charts update <chartId> --board-id <boardId> --body '<json>'`
 Update a chart.
 
-### `charts delete <chartId> --boardId <boardId>`
+### `charts delete <chartId> --board-id <boardId>`
 Delete a chart.
 
 ---
@@ -291,7 +292,7 @@ List all user segments.
 | Option | Description |
 |---|---|
 | `--title` | Segment title |
-| `--filterSets` | JSON array of filter set strings defining the segment |
+| `--filter-sets` | JSON array of filter set strings defining the segment |
 
 ### `segments delete <segmentId>`
 Delete a user segment.
@@ -313,6 +314,31 @@ formo query run "SELECT address, net_worth_usd FROM wallet_profiles ORDER BY net
 
 ---
 
+## `formo analytics`
+
+Pre-built analytics pipes — the same data that powers the Formo dashboard — without writing SQL. Each pipe is a subcommand: `formo analytics <pipe>`.
+
+**Pipes:** `kpis`, `event_timeseries`, `funnel`, `flow`, `frequency`, `lifecycle`, `retention`, `revenue_overview`, `revenue_by_metric`, `revenue_timeseries`, `volume_by_metric`, `top_chains`, `top_events`, `top_locations`, `top_pages`, `top_sources`, `top_wallets`
+
+| Option | Description |
+|---|---|
+| `--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"`) |
+| `--params` | JSON object of pipe-specific params merged into the query (e.g. `{"limit":10,"group_by":"device"}`) |
+
+```bash
+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"}]'
+```
+
+> Requires `query:read` scope. Run `formo analytics <pipe> --help` for the pipe-specific params accepted via `--params`.
+
+---
+
 ## `formo import`
 
 ### `import wallets`
@@ -322,10 +348,10 @@ Bulk-import wallet addresses into the project via the events API.
 | Option | Description |
 |---|---|
 | `--addresses` | JSON array of wallet address strings |
-| `--writeKey` | Project write SDK key |
+| `--write-key` | Project write SDK key |
 
 ```bash
-formo import wallets --addresses '["0xabc...","0xdef..."]' --writeKey write_key_xyz
+formo import wallets --addresses '["0xabc...","0xdef..."]' --write-key write_key_xyz
 ```
 
 ---
@@ -336,16 +362,30 @@ formo import wallets --addresses '["0xabc...","0xdef..."]' --writeKey write_key_
 
 ```json
 [
-  { "field": "net_worth_usd", "op": "gt", "value": 10000 },
-  { "field": "tx_count", "op": "gte", "value": 5 }
+  { "field": "users.net_worth_usd", "op": "gt", "value": 10000 },
+  { "field": "chains.1.balance", "op": "gte", "value": 1000 }
 ]
 ```
 
+> **The `field` must be a typed path.** A bare name like `net_worth_usd` is
+> silently ignored by the API (no error, no filtering — the search returns
+> everything). Always prefix the field with its type.
+
 | Field | Type | Description |
 |---|---|---|
-| `field` | `string` | Profile field to filter on |
+| `field` | `string` | Typed path (see prefixes below) |
 | `op` | `string` | `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `in`, `nin` |
 | `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` |
+
+| Prefix | Examples |
+|---|---|
+| `users.` | `users.net_worth_usd`, `users.volume`, `users.revenue`, `users.points`, `users.device`, `users.location`, `users.lifecycle`, `users.ens`, `users.farcaster` |
+| `chains.` | `chains.balance` (any chain), `chains.1.balance` (Ethereum) |
+| `apps.` | `apps.uniswap-v3.balance` |
+| `tokens.` | `tokens.0xA0b8…48.balance` |
+| `labels.` | `labels.coinbase.verified_account` |
 
 Combine multiple conditions with `--logic and` (default) or `--logic or`.
 

package/dist/commands/alerts.js

@@ -56,7 +56,7 @@ function buildAlertBody(options) {
             body.trigger_filters = JSON.parse(options.triggerFilters);
         }
         catch {
-            throw new Error('--triggerFilters must be a valid JSON array');
+            throw new Error('--trigger-filters must be a valid JSON array');
         }
     }
     if (options.recipient) {

package/dist/commands/analytics.d.ts

@@ -0,0 +1,25 @@
+import { Cli } from 'incur';
+export declare const analytics: Cli.Cli<{}, undefined, undefined>;
+export interface AnalyticsOptions {
+    dateFrom?: string;
+    dateTo?: string;
+    filters?: string;
+    params?: string;
+}
+/**
+ * Build the query-string params for an analytics pipe request.
+ *
+ * - `dateFrom`/`dateTo` map to the API's snake_case `date_from`/`date_to`.
+ *   All pipes, including `funnel` and `flow`, use snake_case.
+ * - `filters` is a JSON array of `{ field, op, value }` objects, re-serialized
+ *   as a JSON string (the pipe expects a JSON-encoded array in the query).
+ * - `params` is a JSON object of any pipe-specific params (e.g. funnel
+ *   `steps`, kpis `group_by`, `limit`). Object/array values are JSON-encoded
+ *   (pipes like funnel expect `steps` as a JSON-encoded string); primitives
+ *   pass through unchanged. Reserved keys (the date/filters flags) are
+ *   rejected, and the validated flags below always take precedence.
+ *
+ * Exported for unit testing.
+ */
+export declare function buildAnalyticsParams(options: AnalyticsOptions): Record<string, string | number | boolean>;
+export declare function runAnalytics(pipe: string, options: AnalyticsOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;

package/dist/commands/analytics.js

@@ -0,0 +1,153 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.analytics = void 0;
+exports.buildAnalyticsParams = buildAnalyticsParams;
+exports.runAnalytics = runAnalytics;
+const incur_1 = require("incur");
+const client_1 = require("../lib/client");
+exports.analytics = incur_1.Cli.create('analytics', {
+    description: 'Pre-built analytics query commands — KPIs, funnels, retention, revenue, and top-N breakdowns',
+});
+// The pre-built analytics pipes exposed at GET /v0/<pipe>. Each requires the
+// query:read scope. Common params (date_from, date_to, filters) are shared;
+// pipe-specific params (e.g. funnel `steps`, kpis `group_by`, `limit`) are
+// passed through the generic --params JSON object.
+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: '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)' },
+    { name: 'retention', description: 'Retention cohort analysis (params: id_type, event_type, event_name, min_users)' },
+    { name: 'revenue_overview', description: 'Revenue overview with optional breakdown (params: group_by, rank_by)' },
+    { name: 'revenue_by_metric', description: 'Revenue ranked by a metric column (params: metric_column, limit, offset)' },
+    { name: 'revenue_timeseries', description: 'Revenue over time (params: address)' },
+    { name: 'volume_by_metric', description: 'Trading volume ranked by a metric column (params: metric_column, limit, offset)' },
+    { name: 'top_chains', description: 'Top chains by activity (params: limit, offset)' },
+    { name: 'top_events', description: 'Top events by count (params: limit, offset, type)' },
+    { name: 'top_locations', description: 'Top locations (params: limit, offset)' },
+    { name: 'top_pages', description: 'Top pages by traffic (params: limit, offset, mode)' },
+    { name: 'top_sources', description: 'Top acquisition sources (params: metric_column, limit, offset)' },
+    { name: 'top_wallets', description: 'Top wallets by activity (params: limit, offset)' },
+];
+// Keys --params is not allowed to set: they have dedicated, validated flags
+// (--date-from/--date-to/--filters). Rejecting them prevents --params from
+// silently overriding validated input or pushing an invalid `filters` value
+// (e.g. a non-JSON string) over the wire. Both casings of the date keys are
+// rejected so a stray camelCase key can't slip through unvalidated.
+const RESERVED_PARAM_KEYS = new Set([
+    'date_from',
+    'date_to',
+    'dateFrom',
+    'dateTo',
+    'filters',
+]);
+/**
+ * Build the query-string params for an analytics pipe request.
+ *
+ * - `dateFrom`/`dateTo` map to the API's snake_case `date_from`/`date_to`.
+ *   All pipes, including `funnel` and `flow`, use snake_case.
+ * - `filters` is a JSON array of `{ field, op, value }` objects, re-serialized
+ *   as a JSON string (the pipe expects a JSON-encoded array in the query).
+ * - `params` is a JSON object of any pipe-specific params (e.g. funnel
+ *   `steps`, kpis `group_by`, `limit`). Object/array values are JSON-encoded
+ *   (pipes like funnel expect `steps` as a JSON-encoded string); primitives
+ *   pass through unchanged. Reserved keys (the date/filters flags) are
+ *   rejected, and the validated flags below always take precedence.
+ *
+ * Exported for unit testing.
+ */
+function buildAnalyticsParams(options) {
+    const out = {};
+    // --params first, so the validated flags below override it.
+    if (options.params) {
+        let parsed;
+        try {
+            parsed = JSON.parse(options.params);
+        }
+        catch {
+            throw new Error('--params must be a valid JSON object');
+        }
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            throw new Error('--params must be a valid JSON object');
+        }
+        for (const [key, value] of Object.entries(parsed)) {
+            if (RESERVED_PARAM_KEYS.has(key)) {
+                throw new Error(`--params may not set "${key}" — use the --date-from/--date-to/--filters flags instead`);
+            }
+            if (value === null || value === undefined)
+                continue;
+            if (typeof value === 'object') {
+                out[key] = JSON.stringify(value);
+            }
+            else {
+                out[key] = value;
+            }
+        }
+    }
+    if (options.dateFrom)
+        out.date_from = options.dateFrom;
+    if (options.dateTo)
+        out.date_to = options.dateTo;
+    if (options.filters) {
+        let parsed;
+        try {
+            parsed = JSON.parse(options.filters);
+        }
+        catch {
+            throw new Error('--filters must be a valid JSON array of {field,op,value} objects');
+        }
+        if (!Array.isArray(parsed)) {
+            throw new Error('--filters must be a valid JSON array of {field,op,value} objects');
+        }
+        out.filters = JSON.stringify(parsed);
+    }
+    return out;
+}
+function runAnalytics(pipe, options) {
+    (0, client_1.requireApiKey)();
+    const client = (0, client_1.createClient)();
+    return client.get(`/v0/${pipe}`, { params: buildAnalyticsParams(options) });
+}
+const sharedOptions = incur_1.z.object({
+    dateFrom: incur_1.z
+        .string()
+        .optional()
+        .describe('Inclusive start date YYYY-MM-DD (default: 7 days before --date-to)'),
+    dateTo: incur_1.z
+        .string()
+        .optional()
+        .describe('Inclusive end date YYYY-MM-DD (default: today)'),
+    filters: incur_1.z
+        .string()
+        .optional()
+        .describe('JSON array of filter conditions: [{"field","op","value"}]. ' +
+        'Use op "in"/"notIn" with a pipe-delimited value (e.g. "chrome|firefox").'),
+    params: incur_1.z
+        .string()
+        .optional()
+        .describe('JSON object of pipe-specific params merged into the query, e.g. ' +
+        '{"limit":10,"group_by":"device"} or funnel ' +
+        '{"steps":[{"type":"event","event":"page","name":"page::0","filters":[]}]}. ' +
+        'May not set date_from/date_to/filters; use the dedicated --date-from/--date-to/--filters flags.'),
+});
+for (const pipe of PIPES) {
+    exports.analytics.command(pipe.name, {
+        description: pipe.description,
+        options: sharedOptions,
+        examples: [
+            {
+                description: `Get ${pipe.name} for the last 7 days (default range)`,
+            },
+            {
+                options: { dateFrom: '2026-04-01', dateTo: '2026-04-30' },
+                description: `Get ${pipe.name} for April 2026`,
+            },
+        ],
+        hint: 'Requires query:read scope on your API key. Pass pipe-specific params via --params.',
+        run({ options }) {
+            return runAnalytics(pipe.name, options);
+        },
+    });
+}

package/dist/commands/profiles.d.ts

@@ -11,6 +11,13 @@ export interface SearchProfilesOptions {
     conditions?: string;
     logic?: 'and' | 'or';
 }
+/**
+ * Parse and validate the --conditions JSON. Ensures it is an array of
+ * `{ field, op, value }` objects whose `field` is a typed path (e.g.
+ * `users.net_worth_usd`) — a bare name like `net_worth_usd` is silently
+ * dropped by the API, so it is rejected here. Exported for unit testing.
+ */
+export declare function parseSearchConditions(raw: string): unknown[];
 export declare function searchProfilesRun(options: SearchProfilesOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;
 export interface UpdateProfileOptions {
     properties: string;

package/dist/commands/profiles.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.profilesLabels = exports.profiles = void 0;
 exports.getProfileRun = getProfileRun;
+exports.parseSearchConditions = parseSearchConditions;
 exports.searchProfilesRun = searchProfilesRun;
 exports.buildUpdateProfileBody = buildUpdateProfileBody;
 exports.updateProfileRun = updateProfileRun;
@@ -41,10 +42,60 @@ exports.profiles.command('get', {
             description: 'Get profile with expanded labels and chains',
         },
     ],
+    hint: 'Requires profiles:read scope on your API key.',
     run({ args, options }) {
         return getProfileRun(args.address, options.expand);
     },
 });
+// Accepted first segments for a FilterCondition `field`, mirroring the API's
+// parseField(). A field whose prefix is not one of these is silently ignored
+// server-side (no error, no filtering — the search returns everything), so we
+// reject it client-side with an actionable message instead.
+const CONDITION_FIELD_PREFIXES = new Set([
+    'user',
+    'users',
+    'chain',
+    'chains',
+    'app',
+    'apps',
+    'token',
+    'tokens',
+    'label',
+    'labels',
+]);
+/**
+ * Parse and validate the --conditions JSON. Ensures it is an array of
+ * `{ field, op, value }` objects whose `field` is a typed path (e.g.
+ * `users.net_worth_usd`) — a bare name like `net_worth_usd` is silently
+ * dropped by the API, so it is rejected here. Exported for unit testing.
+ */
+function parseSearchConditions(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error('--conditions must be a valid JSON array of FilterCondition objects');
+    }
+    if (!Array.isArray(parsed)) {
+        throw new Error('--conditions must be a valid JSON array of FilterCondition objects');
+    }
+    for (const cond of parsed) {
+        if (!cond || typeof cond !== 'object' || Array.isArray(cond)) {
+            throw new Error('--conditions: each entry must be an object with field, op, value');
+        }
+        const field = cond.field;
+        if (typeof field !== 'string' || field.length === 0) {
+            throw new Error('--conditions: each entry must have a non-empty string "field"');
+        }
+        if (!field.includes('.') || !CONDITION_FIELD_PREFIXES.has(field.split('.')[0])) {
+            throw new Error(`--conditions: field "${field}" must be a typed path — prefix it with ` +
+                'users., chains., apps., tokens., or labels. ' +
+                '(a bare name is silently ignored by the API and returns the entire unfiltered dataset)');
+        }
+    }
+    return parsed;
+}
 function searchProfilesRun(options) {
     (0, client_1.requireApiKey)();
     const client = (0, client_1.createClient)();
@@ -63,15 +114,10 @@ function searchProfilesRun(options) {
         params.expand = options.expand;
     let body;
     if (options.conditions) {
-        try {
-            const conditions = JSON.parse(options.conditions);
-            if (!Array.isArray(conditions))
-                throw new Error('not an array');
-            body = { conditions, logic: options.logic ?? 'and' };
-        }
-        catch {
-            throw new Error('--conditions must be valid JSON array of FilterCondition objects');
-        }
+        body = {
+            conditions: parseSearchConditions(options.conditions),
+            logic: options.logic ?? 'and',
+        };
     }
     return client.request({ method: 'get', url: '/v0/profiles/', params, data: body });
 }
@@ -102,7 +148,15 @@ exports.profiles.command('search', {
         conditions: incur_1.z
             .string()
             .optional()
-            .describe('JSON array of FilterCondition objects for advanced filtering'),
+            .describe('JSON array of FilterCondition objects: [{"field","op","value"}]. ' +
+            'The "field" MUST be a typed path — a bare name like "net_worth_usd" is silently ignored. ' +
+            'Profile: users.net_worth_usd, users.volume, users.revenue, users.points. ' +
+            'Engagement: users.device, users.browser, users.os, users.location, users.lifecycle. ' +
+            'Socials: users.ens, users.farcaster, users.lens, etc. ' +
+            '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.'),
         logic: incur_1.z
             .enum(['and', 'or'])
             .optional()
@@ -120,20 +174,28 @@ exports.profiles.command('search', {
         },
         {
             options: {
-                conditions: '[{"field":"net_worth_usd","op":"gt","value":10000}]',
+                conditions: '[{"field":"users.net_worth_usd","op":"gt","value":10000}]',
                 size: 20,
             },
-            description: 'Search profiles with net worth > 10000',
+            description: 'Search profiles with net worth > $10k',
         },
         {
             options: {
-                conditions: '[{"field":"net_worth_usd","op":"gt","value":10000},{"field":"tx_count","op":"gt","value":50}]',
+                conditions: '[{"field":"users.net_worth_usd","op":"gt","value":10000},{"field":"users.volume","op":"gt","value":1000}]',
                 logic: 'or',
                 size: 20,
             },
-            description: 'Search profiles matching either condition',
+            description: 'Search profiles matching either condition (net worth or volume)',
+        },
+        {
+            options: {
+                conditions: '[{"field":"chains.1.balance","op":"gt","value":1000}]',
+                size: 20,
+            },
+            description: 'Search profiles with > $1k balance on Ethereum (chain 1)',
         },
     ],
+    hint: 'Requires profiles:read scope on your API key. Filter "field" must be a typed path (e.g. users.net_worth_usd) — bare names are ignored by the API.',
     run({ args: _args, options }) {
         return searchProfilesRun(options);
     },
@@ -211,7 +273,7 @@ function buildCreateLabelBody(options) {
             single.chain_id = options.chainId;
         return single;
     }
-    throw new Error('Provide --tagId (single label) or --labels (batch JSON array)');
+    throw new Error('Provide --tag-id (single label) or --labels (batch JSON array)');
 }
 function createProfileLabelRun(address, options) {
     (0, client_1.requireApiKey)();
@@ -259,7 +321,7 @@ exports.profilesLabels.command('create', {
 });
 function buildDeleteLabelBody(options) {
     if (!options.tagId) {
-        throw new Error('--tagId is required');
+        throw new Error('--tag-id is required');
     }
     const body = { tag_id: options.tagId };
     if (options.chainId)

package/dist/commands/segments.js

@@ -30,7 +30,7 @@ function buildCreateSegmentBody(options) {
         parsedFilterSets = JSON.parse(options.filterSets);
     }
     catch {
-        throw new Error('--filterSets must be a valid JSON array');
+        throw new Error('--filter-sets must be a valid JSON array');
     }
     return {
         title: options.title,

package/dist/index.js

@@ -3,6 +3,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const incur_1 = require("incur");
 const alerts_1 = require("./commands/alerts");
+const analytics_1 = require("./commands/analytics");
 const boards_1 = require("./commands/boards");
 const charts_1 = require("./commands/charts");
 const contracts_1 = require("./commands/contracts");
@@ -64,6 +65,9 @@ const cli = incur_1.Cli.create("formo", {
             "get the profile for wallet 0xabc",
             "search profiles with net worth > 10000",
             "run a SQL query on my analytics data",
+            "show traffic KPIs for the last 7 days",
+            "get the conversion funnel for the last month",
+            "list the top wallets by activity",
             "search profiles ordered by last_onchain desc",
             "list all project alerts",
             "create an alert for high-value transactions",
@@ -234,6 +238,7 @@ cli.command("status", {
 // ── command groups ──
 cli.command(profiles_1.profiles);
 cli.command(query_1.query);
+cli.command(analytics_1.analytics);
 cli.command(alerts_1.alerts);
 cli.command(boards_1.boards);
 cli.command(charts_1.charts);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@formo/cli",
-  "version": "0.2.0",
-  "packageManager": "pnpm@10.28.2",
+  "version": "1.0.0",
+  "packageManager": "pnpm@11.1.2",
   "description": "Formo API CLI — query profiles and analytics data",
   "repository": {
     "type": "git",
@@ -29,7 +29,7 @@
     "test:watch": "mocha --watch"
   },
   "dependencies": {
-    "axios": "^1.7.0",
+    "axios": "^1.15.2",
     "incur": "^0.3.4"
   },
   "overrides": {