@formo/cli 0.1.0

package/README.md

@@ -0,0 +1,142 @@
+# @formo/cli
+
+Command-line interface for the Formo API. Query wallet profiles and run analytics SQL queries directly from your terminal or via AI agents.
+
+## Installation
+
+```bash
+npm install -g @formo/cli
+# or use without installing:
+npx @formo/cli
+```
+
+## Authentication
+
+Authenticate by saving your API key:
+
+```bash
+formo login <apiKey>
+```
+
+Or set the `FORMO_API_KEY` environment variable — it takes precedence over the saved config:
+
+```bash
+export FORMO_API_KEY=formo_abc123
+```
+
+## Commands
+
+### `formo login`
+
+Save your API key to `~/.config/formo/config.json`.
+
+| Argument | Description |
+|---|---|
+| `apiKey` | Your `formo_` API key |
+
+```bash
+formo login formo_abc123
+```
+
+---
+
+### `formo profiles get`
+
+Fetch a single wallet profile by address or ENS name.
+
+| Argument | Description |
+|---|---|
+| `address` | Wallet address (`0x…`) or ENS name |
+
+| Option | Description |
+|---|---|
+| `--expand` | Comma-separated fields to expand: `apps`, `chains`, `tokens`, `labels` |
+
+```bash
+formo profiles get 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
+formo profiles get vitalik.eth --expand labels,chains
+```
+
+---
+
+### `formo profiles search`
+
+Search wallet profiles with optional filters and sorting.
+
+| Option | Description |
+|---|---|
+| `--address` | Filter by wallet address |
+| `--limit` | Max results to return |
+| `--offset` | Pagination offset |
+| `--orderBy` | Field to sort by (see values below) |
+| `--orderDir` | Sort direction: `asc` or `desc` |
+| `--expand` | Comma-separated fields to expand |
+| `--conditions` | JSON array of `FilterCondition` objects (see below) |
+
+**`--orderBy` values:** `last_onchain`, `first_onchain`, `net_worth_usd`, `updated_at`, `tx_count`, `first_seen`, `last_seen`, `num_sessions`, `revenue`, `volume`, `points`
+
+```bash
+# First 10 profiles
+formo profiles search --limit 10
+
+# Top 5 by net worth
+formo profiles search --orderBy net_worth_usd --orderDir desc --limit 5
+
+# Advanced filter with conditions
+formo profiles search --conditions '[{"field":"net_worth_usd","op":"gt","value":10000}]' --limit 20
+```
+
+---
+
+### `formo query run`
+
+Run a SQL query against your Formo analytics data.
+
+```bash
+formo query run "SELECT count(*) FROM events"
+formo query run "SELECT address, net_worth_usd FROM wallet_profiles ORDER BY net_worth_usd DESC LIMIT 10"
+```
+
+> Requires `query:read` scope on your API key.
+
+---
+
+## FilterCondition reference
+
+The `--conditions` option accepts a JSON array of filter condition objects:
+
+```json
+[
+  { "field": "net_worth_usd", "op": "gt", "value": 10000 },
+  { "field": "tx_count", "op": "gte", "value": 5 }
+]
+```
+
+| Field | Type | Description |
+|---|---|---|
+| `field` | `string` | Profile field to filter on |
+| `op` | `string` | Operator: `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `in`, `nin` |
+| `value` | `any` | Value to compare against |
+
+Multiple conditions are combined with `AND` logic.
+
+---
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Run in development mode
+pnpm --filter @formo/cli dev
+
+# Build TypeScript
+pnpm --filter @formo/cli build
+
+# Run tests
+pnpm --filter @formo/cli test
+
+# Watch tests
+pnpm --filter @formo/cli test:watch
+```

package/dist/commands/alerts.d.ts

@@ -0,0 +1,22 @@
+import { Cli } from 'incur';
+export declare const alerts: Cli.Cli<{}, undefined, undefined>;
+export declare function listAlertsRun(): Promise<import("axios").AxiosResponse<any, any, {}>>;
+export declare function getAlertRun(alertId: string): Promise<import("axios").AxiosResponse<any, any, {}>>;
+export interface CreateAlertOptions {
+    name: string;
+    triggerType: string;
+    triggerFilters?: string;
+    recipient?: string;
+    secret?: string;
+}
+export declare function createAlertRun(options: CreateAlertOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;
+export interface UpdateAlertOptions {
+    name: string;
+    triggerType: string;
+    triggerFilters?: string;
+    recipient?: string;
+    secret?: 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, {}>>;

package/dist/commands/alerts.js

@@ -0,0 +1,204 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.alerts = void 0;
+exports.listAlertsRun = listAlertsRun;
+exports.getAlertRun = getAlertRun;
+exports.createAlertRun = createAlertRun;
+exports.updateAlertRun = updateAlertRun;
+exports.deleteAlertRun = deleteAlertRun;
+exports.toggleAlertRun = toggleAlertRun;
+const incur_1 = require("incur");
+const client_1 = require("../lib/client");
+exports.alerts = incur_1.Cli.create('alerts', {
+    description: 'Project alert commands — create, list, update, and delete alerts',
+});
+// ── List alerts ──
+function listAlertsRun() {
+    (0, client_1.requireApiKey)();
+    const client = (0, client_1.createClient)();
+    return client.get('/v0/alerts/');
+}
+exports.alerts.command('list', {
+    description: 'List all alerts for the project',
+    examples: [{ description: 'List all project alerts' }],
+    hint: 'Requires alerts:read scope on your API key.',
+    run() {
+        return listAlertsRun();
+    },
+});
+// ── Get a single alert ──
+function getAlertRun(alertId) {
+    (0, client_1.requireApiKey)();
+    const client = (0, client_1.createClient)();
+    return client.get(`/v0/alerts/${encodeURIComponent(alertId)}`);
+}
+exports.alerts.command('get', {
+    description: 'Get a single alert by ID',
+    args: incur_1.z.object({
+        alertId: incur_1.z.string().describe('Alert ID'),
+    }),
+    examples: [
+        { args: { alertId: 'alert_abc123' }, description: 'Get alert details' },
+    ],
+    hint: 'Requires alerts:read scope on your API key.',
+    run({ args }) {
+        return getAlertRun(args.alertId);
+    },
+});
+function createAlertRun(options) {
+    (0, client_1.requireApiKey)();
+    const client = (0, client_1.createClient)();
+    const body = {
+        name: options.name,
+        trigger_type: options.triggerType,
+    };
+    if (options.triggerFilters) {
+        try {
+            body.trigger_filters = JSON.parse(options.triggerFilters);
+        }
+        catch {
+            throw new Error('--triggerFilters must be a valid JSON array');
+        }
+    }
+    if (options.recipient) {
+        try {
+            body.recipient = JSON.parse(options.recipient);
+        }
+        catch {
+            throw new Error('--recipient must be a valid JSON array');
+        }
+    }
+    if (options.secret) {
+        body.secret = options.secret;
+    }
+    return client.post('/v0/alerts/', body);
+}
+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.string().describe('Trigger type (e.g. "event", "threshold")'),
+        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'),
+    }),
+    examples: [
+        {
+            options: { name: 'High value tx', triggerType: 'event' },
+            description: 'Create a basic event alert',
+        },
+    ],
+    hint: 'Requires alerts:write scope on your API key.',
+    run({ options }) {
+        return createAlertRun(options);
+    },
+});
+function updateAlertRun(alertId, options) {
+    (0, client_1.requireApiKey)();
+    const client = (0, client_1.createClient)();
+    const body = {
+        name: options.name,
+        trigger_type: options.triggerType,
+    };
+    if (options.triggerFilters) {
+        try {
+            body.trigger_filters = JSON.parse(options.triggerFilters);
+        }
+        catch {
+            throw new Error('--triggerFilters must be a valid JSON array');
+        }
+    }
+    if (options.recipient) {
+        try {
+            body.recipient = JSON.parse(options.recipient);
+        }
+        catch {
+            throw new Error('--recipient must be a valid JSON array');
+        }
+    }
+    if (options.secret !== undefined) {
+        body.secret = options.secret;
+    }
+    return client.put(`/v0/alerts/${encodeURIComponent(alertId)}`, body);
+}
+exports.alerts.command('update', {
+    description: 'Update an existing alert',
+    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.string().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'),
+    }),
+    examples: [
+        {
+            args: { alertId: 'alert_abc123' },
+            options: { name: 'Renamed alert', triggerType: 'event' },
+            description: 'Update alert name',
+        },
+    ],
+    hint: 'Requires alerts:write scope on your API key.',
+    run({ args, options }) {
+        return updateAlertRun(args.alertId, options);
+    },
+});
+// ── Delete an alert ──
+function deleteAlertRun(alertId) {
+    (0, client_1.requireApiKey)();
+    const client = (0, client_1.createClient)();
+    return client.delete(`/v0/alerts/${encodeURIComponent(alertId)}`);
+}
+exports.alerts.command('delete', {
+    description: 'Delete an alert',
+    args: incur_1.z.object({
+        alertId: incur_1.z.string().describe('Alert ID to delete'),
+    }),
+    examples: [
+        { args: { alertId: 'alert_abc123' }, description: 'Delete an alert' },
+    ],
+    hint: 'Requires alerts:write scope on your API key.',
+    run({ args }) {
+        return deleteAlertRun(args.alertId);
+    },
+});
+// ── Toggle alert status ──
+function toggleAlertRun(alertId, status) {
+    (0, client_1.requireApiKey)();
+    const client = (0, client_1.createClient)();
+    return client.patch(`/v0/alerts/${encodeURIComponent(alertId)}`, { status });
+}
+exports.alerts.command('toggle', {
+    description: 'Toggle an alert status (active/paused)',
+    args: incur_1.z.object({
+        alertId: incur_1.z.string().describe('Alert ID to toggle'),
+    }),
+    options: incur_1.z.object({
+        status: incur_1.z.enum(['active', 'paused']).describe('New status'),
+    }),
+    examples: [
+        {
+            args: { alertId: 'alert_abc123' },
+            options: { status: 'paused' },
+            description: 'Pause an alert',
+        },
+    ],
+    hint: 'Requires alerts:write scope on your API key.',
+    run({ args, options }) {
+        return toggleAlertRun(args.alertId, options.status);
+    },
+});

package/dist/commands/boards.d.ts

@@ -0,0 +1,15 @@
+import { Cli } from 'incur';
+export declare const boards: Cli.Cli<{}, undefined, undefined>;
+export declare function listBoardsRun(): Promise<import("axios").AxiosResponse<any, any, {}>>;
+export declare function getBoardRun(boardId: string): Promise<import("axios").AxiosResponse<any, any, {}>>;
+export interface CreateBoardOptions {
+    name: string;
+    description?: string;
+}
+export declare function createBoardRun(options: CreateBoardOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;
+export interface UpdateBoardOptions {
+    name?: string;
+    description?: string;
+}
+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, {}>>;

package/dist/commands/boards.js

@@ -0,0 +1,126 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.boards = void 0;
+exports.listBoardsRun = listBoardsRun;
+exports.getBoardRun = getBoardRun;
+exports.createBoardRun = createBoardRun;
+exports.updateBoardRun = updateBoardRun;
+exports.deleteBoardRun = deleteBoardRun;
+const incur_1 = require("incur");
+const client_1 = require("../lib/client");
+exports.boards = incur_1.Cli.create('boards', {
+    description: 'Dashboard board commands — create, list, update, and delete boards',
+});
+// ── List boards ──
+function listBoardsRun() {
+    (0, client_1.requireApiKey)();
+    const client = (0, client_1.createClient)();
+    return client.get('/v0/boards/');
+}
+exports.boards.command('list', {
+    description: 'List all boards for the project',
+    examples: [{ description: 'List all dashboard boards' }],
+    hint: 'Requires boards:read scope on your API key.',
+    run() {
+        return listBoardsRun();
+    },
+});
+// ── Get a single board ──
+function getBoardRun(boardId) {
+    (0, client_1.requireApiKey)();
+    const client = (0, client_1.createClient)();
+    return client.get(`/v0/boards/${encodeURIComponent(boardId)}`);
+}
+exports.boards.command('get', {
+    description: 'Get a single board by ID',
+    args: incur_1.z.object({
+        boardId: incur_1.z.string().describe('Board ID'),
+    }),
+    examples: [
+        { args: { boardId: 'board_abc123' }, description: 'Get board details' },
+    ],
+    hint: 'Requires boards:read scope on your API key.',
+    run({ args }) {
+        return getBoardRun(args.boardId);
+    },
+});
+function createBoardRun(options) {
+    (0, client_1.requireApiKey)();
+    const client = (0, client_1.createClient)();
+    const body = { name: options.name };
+    if (options.description) {
+        body.description = options.description;
+    }
+    return client.post('/v0/boards/', body);
+}
+exports.boards.command('create', {
+    description: 'Create a new dashboard board',
+    options: incur_1.z.object({
+        name: incur_1.z.string().describe('Board name'),
+        description: incur_1.z.string().optional().describe('Board description'),
+    }),
+    examples: [
+        {
+            options: { name: 'KPI Dashboard' },
+            description: 'Create a board',
+        },
+        {
+            options: { name: 'Revenue Metrics', description: 'Weekly revenue tracking' },
+            description: 'Create a board with description',
+        },
+    ],
+    hint: 'Requires boards:write scope on your API key.',
+    run({ options }) {
+        return createBoardRun(options);
+    },
+});
+function updateBoardRun(boardId, options) {
+    (0, client_1.requireApiKey)();
+    const client = (0, client_1.createClient)();
+    const body = {};
+    if (options.name !== undefined)
+        body.name = options.name;
+    if (options.description !== undefined)
+        body.description = options.description;
+    return client.patch(`/v0/boards/${encodeURIComponent(boardId)}`, body);
+}
+exports.boards.command('update', {
+    description: 'Update an existing board',
+    args: incur_1.z.object({
+        boardId: incur_1.z.string().describe('Board ID to update'),
+    }),
+    options: incur_1.z.object({
+        name: incur_1.z.string().optional().describe('New board name'),
+        description: incur_1.z.string().optional().describe('New board description'),
+    }),
+    examples: [
+        {
+            args: { boardId: 'board_abc123' },
+            options: { name: 'Renamed Board' },
+            description: 'Rename a board',
+        },
+    ],
+    hint: 'Requires boards:write scope on your API key.',
+    run({ args, options }) {
+        return updateBoardRun(args.boardId, options);
+    },
+});
+// ── Delete a board ──
+function deleteBoardRun(boardId) {
+    (0, client_1.requireApiKey)();
+    const client = (0, client_1.createClient)();
+    return client.delete(`/v0/boards/${encodeURIComponent(boardId)}`);
+}
+exports.boards.command('delete', {
+    description: 'Delete a board',
+    args: incur_1.z.object({
+        boardId: incur_1.z.string().describe('Board ID to delete'),
+    }),
+    examples: [
+        { args: { boardId: 'board_abc123' }, description: 'Delete a board' },
+    ],
+    hint: 'Requires boards:write scope on your API key.',
+    run({ args }) {
+        return deleteBoardRun(args.boardId);
+    },
+});

package/dist/commands/charts.d.ts

@@ -0,0 +1,7 @@
+import { Cli } from 'incur';
+export declare const charts: Cli.Cli<{}, undefined, undefined>;
+export declare function listChartsRun(boardId: string): Promise<import("axios").AxiosResponse<any, any, {}>>;
+export declare function getChartRun(boardId: string, chartId: string): Promise<import("axios").AxiosResponse<any, any, {}>>;
+export declare function createChartRun(boardId: string, body: string): Promise<import("axios").AxiosResponse<any, any, {}>>;
+export declare function updateChartRun(boardId: string, chartId: string, body: string): Promise<import("axios").AxiosResponse<any, any, {}>>;
+export declare function deleteChartRun(boardId: string, chartId: string): Promise<import("axios").AxiosResponse<any, any, {}>>;

package/dist/commands/charts.js

@@ -0,0 +1,157 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.charts = void 0;
+exports.listChartsRun = listChartsRun;
+exports.getChartRun = getChartRun;
+exports.createChartRun = createChartRun;
+exports.updateChartRun = updateChartRun;
+exports.deleteChartRun = deleteChartRun;
+const incur_1 = require("incur");
+const client_1 = require("../lib/client");
+exports.charts = incur_1.Cli.create('charts', {
+    description: 'Chart commands — create, list, update, and delete charts within boards',
+});
+// ── List charts for a board ──
+function listChartsRun(boardId) {
+    (0, client_1.requireApiKey)();
+    const client = (0, client_1.createClient)();
+    return client.get(`/v0/boards/${encodeURIComponent(boardId)}/charts/`);
+}
+exports.charts.command('list', {
+    description: 'List all charts for a board',
+    options: incur_1.z.object({
+        boardId: incur_1.z.string().describe('Board ID to list charts from'),
+    }),
+    examples: [
+        {
+            options: { boardId: 'board_abc123' },
+            description: 'List all charts in a board',
+        },
+    ],
+    hint: 'Requires boards:read scope on your API key.',
+    run({ options }) {
+        return listChartsRun(options.boardId);
+    },
+});
+// ── Get a single chart ──
+function getChartRun(boardId, chartId) {
+    (0, client_1.requireApiKey)();
+    const client = (0, client_1.createClient)();
+    return client.get(`/v0/boards/${encodeURIComponent(boardId)}/charts/${encodeURIComponent(chartId)}`);
+}
+exports.charts.command('get', {
+    description: 'Get a single chart by ID',
+    args: incur_1.z.object({
+        chartId: incur_1.z.string().describe('Chart ID'),
+    }),
+    options: incur_1.z.object({
+        boardId: incur_1.z.string().describe('Board ID the chart belongs to'),
+    }),
+    examples: [
+        {
+            args: { chartId: 'chart_abc123' },
+            options: { boardId: 'board_abc123' },
+            description: 'Get chart details',
+        },
+    ],
+    hint: 'Requires boards:read scope on your API key.',
+    run({ args, options }) {
+        return getChartRun(options.boardId, args.chartId);
+    },
+});
+// ── Create a chart ──
+function createChartRun(boardId, body) {
+    (0, client_1.requireApiKey)();
+    const client = (0, client_1.createClient)();
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        throw new Error('--body must be valid JSON');
+    }
+    return client.post(`/v0/boards/${encodeURIComponent(boardId)}/charts/`, parsed);
+}
+exports.charts.command('create', {
+    description: 'Create a new chart in a board',
+    options: incur_1.z.object({
+        boardId: incur_1.z.string().describe('Board ID to add the chart to'),
+        body: incur_1.z.string().describe('JSON string with chart configuration'),
+    }),
+    examples: [
+        {
+            options: {
+                boardId: 'board_abc123',
+                body: '{"name":"Daily active users","chartType":"line"}',
+            },
+            description: 'Create a line chart',
+        },
+    ],
+    hint: 'Requires boards:write scope on your API key.',
+    run({ options }) {
+        return createChartRun(options.boardId, options.body);
+    },
+});
+// ── Update a chart ──
+function updateChartRun(boardId, chartId, body) {
+    (0, client_1.requireApiKey)();
+    const client = (0, client_1.createClient)();
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        throw new Error('--body must be valid JSON');
+    }
+    return client.put(`/v0/boards/${encodeURIComponent(boardId)}/charts/${encodeURIComponent(chartId)}`, parsed);
+}
+exports.charts.command('update', {
+    description: 'Update an existing chart',
+    args: incur_1.z.object({
+        chartId: incur_1.z.string().describe('Chart ID to update'),
+    }),
+    options: incur_1.z.object({
+        boardId: incur_1.z.string().describe('Board ID the chart belongs to'),
+        body: incur_1.z.string().describe('JSON string with updated chart configuration'),
+    }),
+    examples: [
+        {
+            args: { chartId: 'chart_abc123' },
+            options: {
+                boardId: 'board_abc123',
+                body: '{"name":"Updated chart name"}',
+            },
+            description: 'Update a chart',
+        },
+    ],
+    hint: 'Requires boards:write scope on your API key.',
+    run({ args, options }) {
+        return updateChartRun(options.boardId, args.chartId, options.body);
+    },
+});
+// ── Delete a chart ──
+function deleteChartRun(boardId, chartId) {
+    (0, client_1.requireApiKey)();
+    const client = (0, client_1.createClient)();
+    return client.delete(`/v0/boards/${encodeURIComponent(boardId)}/charts/${encodeURIComponent(chartId)}`);
+}
+exports.charts.command('delete', {
+    description: 'Delete a chart',
+    args: incur_1.z.object({
+        chartId: incur_1.z.string().describe('Chart ID to delete'),
+    }),
+    options: incur_1.z.object({
+        boardId: incur_1.z.string().describe('Board ID the chart belongs to'),
+    }),
+    examples: [
+        {
+            args: { chartId: 'chart_abc123' },
+            options: { boardId: 'board_abc123' },
+            description: 'Delete a chart',
+        },
+    ],
+    hint: 'Requires boards:write scope on your API key.',
+    run({ args, options }) {
+        return deleteChartRun(options.boardId, args.chartId);
+    },
+});

package/dist/commands/contracts.d.ts

@@ -0,0 +1,18 @@
+import { Cli } from 'incur';
+export declare const contracts: Cli.Cli<{}, undefined, undefined>;
+export declare function listContractsRun(): Promise<import("axios").AxiosResponse<any, any, {}>>;
+export interface CreateContractOptions {
+    address: string;
+    chain: number;
+    name: string;
+    abi: string;
+    events: string;
+}
+export declare function createContractRun(options: CreateContractOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;
+export interface UpdateContractOptions {
+    name: string;
+    abi: string;
+    events: string;
+}
+export declare function updateContractRun(chain: string, address: string, options: UpdateContractOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;
+export declare function deleteContractRun(chain: string, address: string): Promise<import("axios").AxiosResponse<any, any, {}>>;