@formo/cli 1.0.2 → 1.1.1

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:
 
@@ -87,6 +104,7 @@ Search wallet profiles with filters, sorting, and pagination. Returns a `Paginat
 | Option | Description |
 |---|---|
 | `--address` | Filter by wallet address |
+| `--search` | Free-text search across address and identity fields |
 | `--page` | Page number (1-indexed, default `1`) |
 | `--size` | Page size (default `100`, max `1000`) |
 | `--order-by` | `last_onchain`, `first_onchain`, `net_worth_usd`, `updated_at`, `tx_count`, `first_seen`, `last_seen`, `num_sessions`, `revenue`, `volume`, `points` |
@@ -104,6 +122,20 @@ formo profiles search --conditions '[{"field":"users.net_worth_usd","op":"gt","v
 formo profiles search --conditions '[{"field":"chains.1.balance","op":"gt","value":1000}]' --size 20
 ```
 
+### Lifecycle tuning (advanced)
+
+Both `profiles get` and `profiles search` accept optional flags to override the lifecycle stage thresholds used when computing `lifecycle`:
+
+| Option | Description |
+|---|---|
+| `--new-window-days` | Override lifecycle new-user window in days |
+| `--churn-window-days` | Override lifecycle churn window in days |
+| `--power-user-min-active-days` | Override lifecycle power-user minimum active days |
+| `--power-user-window-days` | Override lifecycle power-user window in days |
+| `--resurrected-gap-days` | Override lifecycle resurrected gap in days |
+| `--at-risk-min-days-inactive` | Override lifecycle at-risk minimum inactive days |
+| `--at-risk-prior-active-days-threshold` | Override lifecycle at-risk prior active days threshold |
+
 ### `profiles update <address>`
 
 Merge-update identity properties on a wallet profile.
@@ -188,15 +220,16 @@ Get a single alert by ID.
 | `--trigger-filters` | JSON array of trigger filter objects |
 | `--recipient` | JSON array of recipient objects |
 | `--secret` | Webhook secret |
+| `--slack-property-keys` | JSON array of event/user property keys to include in Slack alerts |
 
 ```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"]}]'
 ```
 
 ### `alerts update <alertId>`
-Same options as `create`. Replaces the alert configuration.
+Same options as `create`. Replaces the alert configuration in full — omitted options are reset to their defaults (e.g. leaving out `--trigger-filters` clears the existing trigger filters).
 
 ### `alerts delete <alertId>`
 Delete an alert.
@@ -254,7 +287,7 @@ Delete a board.
 
 ## `formo charts`
 
-Chart commands. Charts live inside a board. Requires `charts:read` / `charts:write`.
+Chart commands. Charts live inside a board. Requires `boards:read` / `boards:write`.
 
 ### `charts list --board-id <boardId>`
 List all charts in a board.
@@ -277,8 +310,12 @@ formo charts create --board-id brd_123 --title "Daily Active Users" \
 formo charts create --board-id brd_123 --body '{"title":"Recent Events","chart_type":"table","query":"SELECT * FROM events LIMIT 10"}'
 ```
 
-### `charts update <chartId> --board-id <boardId> --body '<json>'`
-Update a chart.
+### `charts update <chartId> --board-id <boardId> [options]`
+Update a chart. Accepts the same options as `create`: a raw `--body '<json>'` and/or typed flags (`--title`, `--chart-type`, `--query`, `--description`, `--x-axis`, `--y-axis`, `--group-by`, `--steps`, `--settings`). Typed flags override matching `--body` keys.
+
+```bash
+formo charts update chart_abc123 --board-id brd_123 --title "Renamed chart"
+```
 
 ### `charts query <chartId> --board-id <boardId> --date-from <YYYY-MM-DD> --date-to <YYYY-MM-DD>`
 Execute a saved chart that uses `{{date_from}}` / `{{date_to}}` variables.
@@ -384,7 +421,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 +429,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`.
@@ -403,7 +440,7 @@ formo analytics retention --filters '[{"field":"location","op":"equals","value":
 
 ### `import wallets`
 
-Bulk-import wallet addresses into the project via the events API.
+Bulk-import wallet addresses into the project via the main Formo API, authenticated with your workspace API key.
 
 | Option | Description |
 |---|---|
@@ -415,17 +452,26 @@ formo import wallets --addresses '["0xabc...","0xdef..."]'
 formo import wallets --rows '[{"address":"0xabc...","properties":{"display_name":"Alice"}}]'
 ```
 
+> Requires `profiles:write` scope. Only available on Scale and Enterprise plans.
+
 ---
 
 ## `formo events`
 
 ### `events ingest`
 
-Send raw analytics events to `events.formo.so`. This command uses a project SDK write key, not the workspace API key.
+Send raw analytics events to `events.formo.so`. This command uses a project SDK write key, not the workspace API key — pass it via `--write-key` or the `FORMO_WRITE_KEY` environment variable.
+
+| Option | Description |
+|---|---|
+| `--event` | Single event as a JSON object; wrapped in an array before sending |
+| `--events` | JSON array of event objects to send as a batch |
+| `--write-key` | Project SDK write key (defaults to `FORMO_WRITE_KEY`) |
 
 ```bash
 export FORMO_WRITE_KEY=formo_write_key_xxx
 formo events ingest --event '{"type":"track","channel":"cli","version":"1","anonymous_id":"anon_123","event":"CLI Test","context":{},"properties":{},"original_timestamp":"2026-04-27T23:05:38.000Z","sent_at":"2026-04-27T23:05:42.000Z","message_id":"cli-test-1"}'
+formo events ingest --events '[{"type":"track","event":"First"},{"type":"track","event":"Second"}]'
 ```
 
 ---
@@ -448,7 +494,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/alerts.d.ts

@@ -1,36 +1,28 @@
 import { Cli } from 'incur';
+import { type PaginationOptions } from '../lib/pagination';
+export type { PaginationOptions };
 export declare const alerts: Cli.Cli<{}, undefined, undefined>;
-export interface PaginationOptions {
-    page?: number;
-    size?: number;
-}
-export declare function listAlertsRun(options?: PaginationOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;
-export declare function getAlertRun(alertId: string): Promise<import("axios").AxiosResponse<any, any, {}>>;
-export interface CreateAlertOptions {
-    name: string;
-    triggerType: 'event' | 'user' | string;
-    triggerFilters?: string;
-    recipient?: string;
-    secret?: string;
-    slackPropertyKeys?: string;
-}
-export declare function buildAlertBody(options: CreateAlertOptions | UpdateAlertOptions): Record<string, unknown>;
-export declare function createAlertRun(options: CreateAlertOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;
-export interface UpdateAlertOptions {
+export declare function listAlertsRun(options?: PaginationOptions): Promise<unknown>;
+export declare function getAlertRun(alertId: string): Promise<unknown>;
+export interface AlertBodyOptions {
     name: string;
-    triggerType: 'event' | 'user' | string;
+    triggerType: string;
     triggerFilters?: string;
     recipient?: string;
     secret?: string;
     slackPropertyKeys?: string;
 }
-export declare function updateAlertRun(alertId: string, options: UpdateAlertOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;
-export declare function deleteAlertRun(alertId: string): Promise<import("axios").AxiosResponse<any, any, {}>>;
-export declare function toggleAlertRun(alertId: string, status: string): Promise<import("axios").AxiosResponse<any, any, {}>>;
+export type CreateAlertOptions = AlertBodyOptions;
+export type UpdateAlertOptions = AlertBodyOptions;
+export declare function buildAlertBody(options: AlertBodyOptions): Record<string, unknown>;
+export declare function createAlertRun(options: CreateAlertOptions): Promise<unknown>;
+export declare function updateAlertRun(alertId: string, options: AlertBodyOptions): Promise<unknown>;
+export declare function deleteAlertRun(alertId: string): Promise<unknown>;
+export declare function toggleAlertRun(alertId: string, status: string): Promise<unknown>;
 export interface TestAlertOptions {
     sampleEvent?: string;
     sampleUser?: string;
     recipientOverrides?: string;
 }
 export declare function buildTestAlertBody(options: TestAlertOptions): Record<string, unknown> | undefined;
-export declare function testAlertRun(alertId: string, options?: TestAlertOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;
+export declare function testAlertRun(alertId: string, options?: TestAlertOptions): Promise<unknown>;

package/dist/commands/alerts.js

@@ -13,28 +13,19 @@ exports.testAlertRun = testAlertRun;
 const incur_1 = require("incur");
 const client_1 = require("../lib/client");
 const json_1 = require("../lib/json");
+const pagination_1 = require("../lib/pagination");
 exports.alerts = incur_1.Cli.create('alerts', {
     description: 'Project alert commands — create, list, update, and delete alerts',
 });
-function buildPaginationParams(options = {}) {
-    const params = {};
-    if (options.page !== undefined)
-        params.page = options.page;
-    if (options.size !== undefined)
-        params.size = options.size;
-    return params;
-}
+// ── List alerts ──
 function listAlertsRun(options = {}) {
     (0, client_1.requireApiKey)();
     const client = (0, client_1.createClient)();
-    return client.get('/v0/alerts/', { params: buildPaginationParams(options) });
+    return client.get('/v0/alerts/', { params: (0, pagination_1.buildPaginationParams)(options) });
 }
 exports.alerts.command('list', {
     description: 'List all alerts for the project',
-    options: incur_1.z.object({
-        page: incur_1.z.coerce.number().optional().describe('Page number (1-indexed, default 1)'),
-        size: incur_1.z.coerce.number().optional().describe('Page size (default 100, max 200)'),
-    }),
+    options: incur_1.z.object(pagination_1.paginationOptionsSchema),
     examples: [{ description: 'List all project alerts' }],
     hint: 'Requires alerts:read scope on your API key.',
     run({ options }) {
@@ -60,6 +51,24 @@ exports.alerts.command('get', {
         return getAlertRun(args.alertId);
     },
 });
+// Shared option fragment for `create` and `update` (same PUT/POST body).
+const alertBodyOptionsSchema = {
+    name: incur_1.z.string().describe('Alert name'),
+    triggerType: incur_1.z.enum(['event', 'user']).describe('Trigger type'),
+    triggerFilters: incur_1.z
+        .string()
+        .optional()
+        .describe('JSON array of trigger filter objects'),
+    recipient: incur_1.z
+        .string()
+        .optional()
+        .describe('JSON array of recipient objects'),
+    secret: incur_1.z.string().optional().describe('Webhook secret for the alert'),
+    slackPropertyKeys: incur_1.z
+        .string()
+        .optional()
+        .describe('JSON array of event/user property keys to include in Slack alerts'),
+};
 function buildAlertBody(options) {
     const body = {
         name: options.name,
@@ -87,23 +96,7 @@ function createAlertRun(options) {
 }
 exports.alerts.command('create', {
     description: 'Create a new project alert',
-    options: incur_1.z.object({
-        name: incur_1.z.string().describe('Alert name'),
-        triggerType: incur_1.z.enum(['event', 'user']).describe('Trigger type'),
-        triggerFilters: incur_1.z
-            .string()
-            .optional()
-            .describe('JSON array of trigger filter objects'),
-        recipient: incur_1.z
-            .string()
-            .optional()
-            .describe('JSON array of recipient objects'),
-        secret: incur_1.z.string().optional().describe('Webhook secret for the alert'),
-        slackPropertyKeys: incur_1.z
-            .string()
-            .optional()
-            .describe('JSON array of event/user property keys to include in Slack alerts'),
-    }),
+    options: incur_1.z.object(alertBodyOptionsSchema),
     examples: [
         {
             options: { name: 'High value tx', triggerType: 'event' },
@@ -115,33 +108,18 @@ exports.alerts.command('create', {
         return createAlertRun(options);
     },
 });
+// ── Update an alert ──
 function updateAlertRun(alertId, options) {
     (0, client_1.requireApiKey)();
     const client = (0, client_1.createClient)();
     return client.put(`/v0/alerts/${encodeURIComponent(alertId)}`, buildAlertBody(options));
 }
 exports.alerts.command('update', {
-    description: 'Update an existing alert',
+    description: 'Update an existing alert (full replace — omitted options reset to defaults)',
     args: incur_1.z.object({
         alertId: incur_1.z.string().describe('Alert ID to update'),
     }),
-    options: incur_1.z.object({
-        name: incur_1.z.string().describe('Alert name'),
-        triggerType: incur_1.z.enum(['event', 'user']).describe('Trigger type'),
-        triggerFilters: incur_1.z
-            .string()
-            .optional()
-            .describe('JSON array of trigger filter objects'),
-        recipient: incur_1.z
-            .string()
-            .optional()
-            .describe('JSON array of recipient objects'),
-        secret: incur_1.z.string().optional().describe('Webhook secret for the alert'),
-        slackPropertyKeys: incur_1.z
-            .string()
-            .optional()
-            .describe('JSON array of event/user property keys to include in Slack alerts'),
-    }),
+    options: incur_1.z.object(alertBodyOptionsSchema),
     examples: [
         {
             args: { alertId: 'alert_abc123' },

package/dist/commands/analytics.d.ts

@@ -22,4 +22,4 @@ export interface AnalyticsOptions {
  * 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, {}>>;
+export declare function runAnalytics(pipe: string, options: AnalyticsOptions): Promise<unknown>;

package/dist/commands/analytics.js

@@ -5,6 +5,7 @@ exports.buildAnalyticsParams = buildAnalyticsParams;
 exports.runAnalytics = runAnalytics;
 const incur_1 = require("incur");
 const client_1 = require("../lib/client");
+const json_1 = require("../lib/json");
 exports.analytics = incur_1.Cli.create('analytics', {
     description: 'Pre-built analytics query commands — KPIs, funnels, retention, revenue, and top-N breakdowns',
 });
@@ -15,7 +16,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)' },
@@ -62,16 +63,7 @@ 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');
-        }
+        const parsed = (0, json_1.parseJsonObject)(options.params, '--params');
         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`);
@@ -123,7 +115,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/boards.d.ts

@@ -1,11 +1,9 @@
 import { Cli } from 'incur';
+import { type PaginationOptions } from '../lib/pagination';
+export type { PaginationOptions };
 export declare const boards: Cli.Cli<{}, undefined, undefined>;
-export interface PaginationOptions {
-    page?: number;
-    size?: number;
-}
-export declare function listBoardsRun(options?: PaginationOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;
-export declare function getBoardRun(boardId: string): Promise<import("axios").AxiosResponse<any, any, {}>>;
+export declare function listBoardsRun(options?: PaginationOptions): Promise<unknown>;
+export declare function getBoardRun(boardId: string): Promise<unknown>;
 export interface CreateBoardOptions {
     title?: string;
     name?: string;
@@ -13,12 +11,12 @@ export interface CreateBoardOptions {
     isPublic?: boolean;
 }
 export declare function buildBoardBody(options: CreateBoardOptions | UpdateBoardOptions): Record<string, unknown>;
-export declare function createBoardRun(options: CreateBoardOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;
+export declare function createBoardRun(options: CreateBoardOptions): Promise<unknown>;
 export interface UpdateBoardOptions {
     title?: string;
     name?: string;
     description?: string;
     isPublic?: boolean;
 }
-export declare function updateBoardRun(boardId: string, options: UpdateBoardOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;
-export declare function deleteBoardRun(boardId: string): Promise<import("axios").AxiosResponse<any, any, {}>>;
+export declare function updateBoardRun(boardId: string, options: UpdateBoardOptions): Promise<unknown>;
+export declare function deleteBoardRun(boardId: string): Promise<unknown>;

package/dist/commands/boards.js

@@ -9,29 +9,19 @@ exports.updateBoardRun = updateBoardRun;
 exports.deleteBoardRun = deleteBoardRun;
 const incur_1 = require("incur");
 const client_1 = require("../lib/client");
+const pagination_1 = require("../lib/pagination");
 exports.boards = incur_1.Cli.create('boards', {
     description: 'Dashboard board commands — create, list, update, and delete boards',
 });
-function buildPaginationParams(options = {}) {
-    const params = {};
-    if (options.page !== undefined)
-        params.page = options.page;
-    if (options.size !== undefined)
-        params.size = options.size;
-    return params;
-}
 // ── List boards ──
 function listBoardsRun(options = {}) {
     (0, client_1.requireApiKey)();
     const client = (0, client_1.createClient)();
-    return client.get('/v0/boards/', { params: buildPaginationParams(options) });
+    return client.get('/v0/boards/', { params: (0, pagination_1.buildPaginationParams)(options) });
 }
 exports.boards.command('list', {
     description: 'List all boards for the project',
-    options: incur_1.z.object({
-        page: incur_1.z.coerce.number().optional().describe('Page number (1-indexed, default 1)'),
-        size: incur_1.z.coerce.number().optional().describe('Page size (default 100, max 200)'),
-    }),
+    options: incur_1.z.object(pagination_1.paginationOptionsSchema),
     examples: [{ description: 'List all dashboard boards' }],
     hint: 'Requires boards:read scope on your API key.',
     run({ options }) {
@@ -62,7 +52,7 @@ function buildBoardBody(options) {
     const body = {};
     if (title !== undefined) {
         if (!title)
-            throw new Error('--title must not be empty');
+            throw new Error('--title (or its deprecated alias --name) must not be empty');
         body.title = title;
     }
     if (options.description !== undefined) {

package/dist/commands/charts.d.ts

@@ -1,9 +1,7 @@
 import { Cli } from 'incur';
+import { type PaginationOptions } from '../lib/pagination';
+export type { PaginationOptions };
 export declare const charts: Cli.Cli<{}, undefined, undefined>;
-export interface PaginationOptions {
-    page?: number;
-    size?: number;
-}
 export interface ChartBodyOptions {
     body?: string;
     query?: string;
@@ -17,18 +15,18 @@ export interface ChartBodyOptions {
     settings?: string;
 }
 export declare function buildChartBody(options: ChartBodyOptions): Record<string, unknown>;
-export declare function listChartsRun(boardId: string, options?: PaginationOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;
-export declare function listChartSummariesRun(boardId: string, options?: PaginationOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;
-export declare function getChartRun(boardId: string, chartId: string): Promise<import("axios").AxiosResponse<any, any, {}>>;
+export declare function listChartsRun(boardId: string, options?: PaginationOptions): Promise<unknown>;
+export declare function listChartSummariesRun(boardId: string, options?: PaginationOptions): Promise<unknown>;
+export declare function getChartRun(boardId: string, chartId: string): Promise<unknown>;
 export interface QueryChartOptions {
     dateFrom: string;
     dateTo: string;
 }
-export declare function queryChartRun(boardId: string, chartId: string, options: QueryChartOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;
-export declare function createChartRun(boardId: string, input: string | ChartBodyOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;
-export declare function updateChartRun(boardId: string, chartId: string, input: string | ChartBodyOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;
-export declare function moveChartRun(boardId: string, chartId: string, targetBoardId: string): Promise<import("axios").AxiosResponse<any, any, {}>>;
+export declare function queryChartRun(boardId: string, chartId: string, options: QueryChartOptions): Promise<unknown>;
+export declare function createChartRun(boardId: string, input: string | ChartBodyOptions): Promise<unknown>;
+export declare function updateChartRun(boardId: string, chartId: string, input: string | ChartBodyOptions): Promise<unknown>;
+export declare function moveChartRun(boardId: string, chartId: string, targetBoardId: string): Promise<unknown>;
 export declare function normalizeDuplicateChartResponse(result: unknown): unknown;
 export declare function duplicateChartRun(boardId: string, chartId: string): Promise<unknown>;
-export declare function reorderChartsRun(boardId: string, chartIds: string): Promise<import("axios").AxiosResponse<any, any, {}>>;
-export declare function deleteChartRun(boardId: string, chartId: string): Promise<import("axios").AxiosResponse<any, any, {}>>;
+export declare function reorderChartsRun(boardId: string, chartIds: string): Promise<unknown>;
+export declare function deleteChartRun(boardId: string, chartId: string): Promise<unknown>;

package/dist/commands/charts.js

@@ -17,6 +17,7 @@ const incur_1 = require("incur");
 const client_1 = require("../lib/client");
 const json_1 = require("../lib/json");
 const sql_1 = require("../lib/sql");
+const pagination_1 = require("../lib/pagination");
 exports.charts = incur_1.Cli.create('charts', {
     description: 'Chart commands — create, list, query, move, duplicate, reorder, update, and delete charts within boards',
 });
@@ -32,14 +33,6 @@ const chartTypeSchema = incur_1.z.enum([
     'user_paths',
     'retention',
 ]);
-function buildPaginationParams(options = {}) {
-    const params = {};
-    if (options.page !== undefined)
-        params.page = options.page;
-    if (options.size !== undefined)
-        params.size = options.size;
-    return params;
-}
 function hasTypedChartFields(options) {
     return [
         options.query,
@@ -120,15 +113,14 @@ function listChartsRun(boardId, options = {}) {
     (0, client_1.requireApiKey)();
     const client = (0, client_1.createClient)();
     return client.get(`/v0/boards/${encodeURIComponent(boardId)}/charts/`, {
-        params: buildPaginationParams(options),
+        params: (0, pagination_1.buildPaginationParams)(options),
     });
 }
 exports.charts.command('list', {
     description: 'List all charts for a board, including executed results',
     options: incur_1.z.object({
         boardId: incur_1.z.string().describe('Board ID to list charts from'),
-        page: incur_1.z.coerce.number().optional().describe('Page number (1-indexed, default 1)'),
-        size: incur_1.z.coerce.number().optional().describe('Page size (default 100, max 200)'),
+        ...pagination_1.paginationOptionsSchema,
     }),
     examples: [
         {
@@ -146,15 +138,14 @@ function listChartSummariesRun(boardId, options = {}) {
     (0, client_1.requireApiKey)();
     const client = (0, client_1.createClient)();
     return client.get(`/v0/boards/${encodeURIComponent(boardId)}/charts/meta`, {
-        params: buildPaginationParams(options),
+        params: (0, pagination_1.buildPaginationParams)(options),
     });
 }
 exports.charts.command('meta', {
     description: 'List lightweight chart metadata for a board without query results',
     options: incur_1.z.object({
         boardId: incur_1.z.string().describe('Board ID to list chart metadata from'),
-        page: incur_1.z.coerce.number().optional().describe('Page number (1-indexed, default 1)'),
-        size: incur_1.z.coerce.number().optional().describe('Page size (default 100, max 200)'),
+        ...pagination_1.paginationOptionsSchema,
     }),
     examples: [
         {
@@ -265,6 +256,11 @@ function updateChartRun(boardId, chartId, input) {
     (0, client_1.requireApiKey)();
     const client = (0, client_1.createClient)();
     const updates = coerceChartBody(input);
+    // The charts endpoint only supports full-body PUT, so emulate a partial
+    // update by fetching the current chart and merging flags over it. Two
+    // consequences: a concurrent edit between the GET and PUT is overwritten,
+    // and fields can't be cleared via typed flags (nulls are normalized to
+    // undefined below) — use --body with explicit nulls to clear.
     return client
         .get(`/v0/boards/${encodeURIComponent(boardId)}/charts/${encodeURIComponent(chartId)}`)
         .then((current) => {

package/dist/commands/contracts.d.ts

@@ -1,12 +1,10 @@
 import { Cli } from 'incur';
+import { type PaginationOptions } from '../lib/pagination';
+export type { PaginationOptions };
 export declare const contracts: Cli.Cli<{}, undefined, undefined>;
-export interface PaginationOptions {
-    page?: number;
-    size?: number;
-}
-export declare function listContractsRun(options?: PaginationOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;
-export declare function getContractRun(chain: string, address: string): Promise<import("axios").AxiosResponse<any, any, {}>>;
-export declare function getContractRecommendationsRun(): Promise<import("axios").AxiosResponse<any, any, {}>>;
+export declare function listContractsRun(options?: PaginationOptions): Promise<unknown>;
+export declare function getContractRun(chain: string, address: string): Promise<unknown>;
+export declare function getContractRecommendationsRun(): Promise<unknown>;
 export interface CreateContractOptions {
     address: string;
     chain: number;
@@ -17,7 +15,7 @@ export interface CreateContractOptions {
     includeInPipeline?: boolean;
 }
 export declare function buildCreateContractBody(options: CreateContractOptions): Record<string, unknown>;
-export declare function createContractRun(options: CreateContractOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;
+export declare function createContractRun(options: CreateContractOptions): Promise<unknown>;
 export interface UpdateContractOptions {
     name: string;
     abi: string;
@@ -26,9 +24,9 @@ export interface UpdateContractOptions {
     includeInPipeline?: boolean;
 }
 export declare function buildUpdateContractBody(chain: string | number, address: string, options: UpdateContractOptions): Record<string, unknown>;
-export declare function updateContractRun(chain: string, address: string, options: UpdateContractOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;
-export declare function updateContractPipelineRun(chain: string, address: string, includeInPipeline: boolean): Promise<import("axios").AxiosResponse<any, any, {}>>;
+export declare function updateContractRun(chain: string, address: string, options: UpdateContractOptions): Promise<unknown>;
+export declare function updateContractPipelineRun(chain: string, address: string, includeInPipeline: boolean): Promise<unknown>;
 export declare function buildUpdateContractPipelineBody(includeInPipeline: boolean): {
     include_in_pipeline: boolean;
 };
-export declare function deleteContractRun(chain: string, address: string): Promise<import("axios").AxiosResponse<any, any, {}>>;
+export declare function deleteContractRun(chain: string, address: string): Promise<unknown>;