@formo/cli 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @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.
+Command-line interface for the Formo API. Manage wallet profiles, alerts, dashboards, charts, contracts, segments, and run analytics SQL — directly from your terminal or via AI agents.
 
 ## Installation
 
@@ -12,7 +12,7 @@ npx @formo/cli
 
 ## Authentication
 
-Authenticate by saving your API key:
+Save your API key locally:
 
 ```bash
 formo login <apiKey>
@@ -24,86 +24,315 @@ Or set the `FORMO_API_KEY` environment variable — it takes precedence over the
 export FORMO_API_KEY=formo_abc123
 ```
 
-## Commands
+Get your API key from `Settings → API Keys` in the [Formo dashboard](https://app.formo.so).
 
-### `formo login`
+---
 
-Save your API key to `~/.config/formo/config.json`.
+## Auth commands
 
-| Argument | Description |
-|---|---|
-| `apiKey` | Your `formo_` API key |
+### `formo login [apiKey]`
+
+Save your API key to `~/.config/formo/config.json`. Validates the key against the API and stores the workspace context.
 
 ```bash
 formo login formo_abc123
 ```
 
+### `formo logout`
+
+Remove the saved API key and clear authentication state.
+
+```bash
+formo logout
+```
+
+### `formo status`
+
+Show current authentication state, workspace, and project ID.
+
+```bash
+formo status
+```
+
 ---
 
-### `formo profiles get`
+## `formo profiles`
 
-Fetch a single wallet profile by address or ENS name.
+Wallet profile commands.
 
-| Argument | Description |
-|---|---|
-| `address` | Wallet address (`0x…`) or ENS name |
+### `profiles get <address>`
+
+Fetch a single wallet profile by address or ENS name.
 
 | Option | Description |
 |---|---|
-| `--expand` | Comma-separated fields to expand: `apps`, `chains`, `tokens`, `labels` |
+| `--expand` | Comma-separated fields: `apps`, `chains`, `tokens`, `labels` |
 
 ```bash
 formo profiles get 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
 formo profiles get vitalik.eth --expand labels,chains
 ```
 
----
-
-### `formo profiles search`
+### `profiles search`
 
-Search wallet profiles with optional filters and sorting.
+Search wallet profiles with filters, sorting, and pagination. Returns a `PaginatedResponse<Profile>`.
 
 | 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` |
+| `--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` |
 | `--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 --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
+```
+
+### `profiles update <address>`
+
+Merge-update identity properties on a wallet profile.
+
+| Option | Description |
+|---|---|
+| `--properties` | JSON object of properties to merge |
+
+**Allowed property keys:** `user_id`, `display_name`, `email`, `farcaster`, `discord`, `twitter`, `telegram`, `instagram`, `website`, `github`, `linkedin`, `facebook`, `tiktok`, `youtube`, `reddit`, `avatar`, `description`, `location`, `ens`, `lens`, `basenames`, `linea`. Unknown keys are rejected server-side.
+
+```bash
+formo profiles update 0xd8dA... --properties '{"display_name":"Vitalik","twitter":"VitalikButerin"}'
+formo profiles update vitalik.eth --properties '{"email":"alice@example.com"}'
+```
+
+> Requires `profiles:write` scope.
+
+### `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`.
 
-**`--orderBy` values:** `last_onchain`, `first_onchain`, `net_worth_usd`, `updated_at`, `tx_count`, `first_seen`, `last_seen`, `num_sessions`, `revenue`, `volume`, `points`
+| Option | Description |
+|---|---|
+| `--tagId` | 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 |
+| `--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... --labels '[{"tag_id":"vip"},{"tag_id":"airdrop_eligible","chain_id":"1"}]'
+```
+
+### `profiles labels delete <address>`
+
+Delete a label from a wallet profile.
+
+| Option | Description |
+|---|---|
+| `--tagId` | Label identifier to delete (required) |
+| `--chainId` | Optional chain identifier to scope the deletion |
+
+```bash
+formo profiles labels delete 0xd8dA... --tagId vip
+formo profiles labels delete 0xd8dA... --tagId tier --chainId 1
+```
+
+> Requires `profiles:write` scope.
+
+---
+
+## `formo alerts`
+
+Project alert commands. Requires `alerts:read` (list/get) or `alerts:write` (create/update/delete/toggle).
+
+### `alerts list`
+List all alerts for the project.
+
+### `alerts get <alertId>`
+Get a single alert by ID.
+
+### `alerts create`
+
+| Option | Description |
+|---|---|
+| `--name` | Alert name |
+| `--triggerType` | Trigger type (e.g. `event`, `threshold`) |
+| `--triggerFilters` | JSON array of trigger filter objects |
+| `--recipient` | JSON array of recipient objects |
+| `--secret` | Webhook secret |
 
 ```bash
-# First 10 profiles
-formo profiles search --limit 10
+formo alerts create --name "High value tx" --triggerType event \
+  --triggerFilters '[{"name":"event","operator":"equals","value":"transaction"}]' \
+  --recipient '[{"type":"email","value":["alerts@myapp.com"]}]'
+```
+
+### `alerts update <alertId>`
+Same options as `create`. Replaces the alert configuration.
 
-# Top 5 by net worth
-formo profiles search --orderBy net_worth_usd --orderDir desc --limit 5
+### `alerts delete <alertId>`
+Delete an alert.
 
-# Advanced filter with conditions
-formo profiles search --conditions '[{"field":"net_worth_usd","op":"gt","value":10000}]' --limit 20
+### `alerts toggle <alertId> --status <active|paused>`
+Toggle an alert between `active` and `paused`.
+
+```bash
+formo alerts toggle alert_abc123 --status paused
 ```
 
 ---
 
-### `formo query run`
+## `formo boards`
+
+Dashboard board commands. Requires `boards:read` / `boards:write`.
+
+### `boards list`
+List all boards for the project.
 
-Run a SQL query against your Formo analytics data.
+### `boards get <boardId>`
+Get a single board by ID.
+
+### `boards create`
+
+| Option | Description |
+|---|---|
+| `--name` | Board name |
+| `--description` | Optional board description |
+
+```bash
+formo boards create --name "Revenue Metrics" --description "Weekly revenue tracking"
+```
+
+### `boards update <boardId>`
+
+| Option | Description |
+|---|---|
+| `--name` | New board name |
+| `--description` | New board description |
+
+### `boards delete <boardId>`
+Delete a board.
+
+---
+
+## `formo charts`
+
+Chart commands. Charts live inside a board. Requires `charts:read` / `charts:write`.
+
+### `charts list --boardId <boardId>`
+List all charts in a board.
+
+### `charts get <chartId> --boardId <boardId>`
+Get a single chart by ID.
+
+### `charts create --boardId <boardId> --body '<json>'`
+Create a chart from a JSON config string.
+
+### `charts update <chartId> --boardId <boardId> --body '<json>'`
+Update a chart.
+
+### `charts delete <chartId> --boardId <boardId>`
+Delete a chart.
+
+---
+
+## `formo contracts`
+
+Smart contract commands. Requires `contracts:read` / `contracts:write`.
+
+### `contracts list`
+List all tracked contracts. Returns `{ data: Contract[], deploy: { last_deployed_at, diff }, total, page, size, has_more }`.
+
+### `contracts create`
+
+| Option | Description |
+|---|---|
+| `--address` | Contract address (`0x…`) |
+| `--chain` | Chain ID (e.g. `1`, `137`) |
+| `--name` | Human-readable contract name |
+| `--abi` | Contract ABI as a JSON string |
+| `--events` | Events configuration as a JSON string |
+
+```bash
+formo contracts create --address 0x1f9840a85d5af5bf1d1762f925bdaddc4201f984 --chain 1 \
+  --name "UNI Token" --abi '[{"type":"event","name":"Transfer","inputs":[]}]' \
+  --events '{"Transfer":true}'
+```
+
+### `contracts update <chain> <address>`
+
+| Option | Description |
+|---|---|
+| `--name` | Updated contract name |
+| `--abi` | Updated ABI |
+| `--events` | Updated events config |
+
+### `contracts delete <chain> <address>`
+Remove a tracked contract.
+
+---
+
+## `formo segments`
+
+User segment commands. Requires `segments:read` / `segments:write`.
+
+### `segments list`
+List all user segments.
+
+### `segments create`
+
+| Option | Description |
+|---|---|
+| `--title` | Segment title |
+| `--filterSets` | JSON array of filter set strings defining the segment |
+
+### `segments delete <segmentId>`
+Delete a user segment.
+
+---
+
+## `formo query`
+
+### `query run "<sql>"`
+
+Run a SQL query against your Formo analytics data. Returns `{ data, total, limit, offset, has_more }`.
 
 ```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.
+> Requires `query:read` scope.
+
+---
+
+## `formo import`
+
+### `import wallets`
+
+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 |
+
+```bash
+formo import wallets --addresses '["0xabc...","0xdef..."]' --writeKey write_key_xyz
+```
 
 ---
 
 ## FilterCondition reference
 
-The `--conditions` option accepts a JSON array of filter condition objects:
+`profiles search --conditions` accepts a JSON array of filter condition objects:
 
 ```json
 [
@@ -115,10 +344,25 @@ The `--conditions` option accepts a JSON array of filter condition objects:
 | Field | Type | Description |
 |---|---|---|
 | `field` | `string` | Profile field to filter on |
-| `op` | `string` | Operator: `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `in`, `nin` |
+| `op` | `string` | `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `in`, `nin` |
 | `value` | `any` | Value to compare against |
 
-Multiple conditions are combined with `AND` logic.
+Combine multiple conditions with `--logic and` (default) or `--logic or`.
+
+---
+
+## Output formats
+
+Every command supports the standard incur output flags:
+
+| Flag | Description |
+|---|---|
+| `--format <toon\|json\|yaml\|md\|jsonl>` | Output format (default: `toon`) |
+| `--json` | Shorthand for `--format json` |
+| `--verbose` | Include the full envelope (`ok`, `data`, `meta`) |
+| `--filter-output <keys>` | Filter output by key paths (e.g. `data,meta.duration`) |
+
+Every list endpoint returns a `PaginatedResponse<T>` envelope: `{ data: [...], total, page, size, has_more }`. Every error follows: `{ error: { code, message, doc_url, param?, details? } }` — branch on `error.code`, not `message`.
 
 ---
 
@@ -129,14 +373,14 @@ Multiple conditions are combined with `AND` logic.
 pnpm install
 
 # Run in development mode
-pnpm --filter @formo/cli dev
+pnpm dev
 
 # Build TypeScript
-pnpm --filter @formo/cli build
+pnpm build
 
-# Run tests
-pnpm --filter @formo/cli test
+# Lint
+pnpm lint
 
-# Watch tests
-pnpm --filter @formo/cli test:watch
+# Run tests (requires TEST_TOKEN in .env)
+pnpm test
 ```

package/dist/commands/alerts.d.ts

@@ -9,6 +9,7 @@ export interface CreateAlertOptions {
     recipient?: string;
     secret?: 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 {
     name: string;

package/dist/commands/alerts.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.alerts = void 0;
 exports.listAlertsRun = listAlertsRun;
 exports.getAlertRun = getAlertRun;
+exports.buildAlertBody = buildAlertBody;
 exports.createAlertRun = createAlertRun;
 exports.updateAlertRun = updateAlertRun;
 exports.deleteAlertRun = deleteAlertRun;
@@ -45,9 +46,7 @@ exports.alerts.command('get', {
         return getAlertRun(args.alertId);
     },
 });
-function createAlertRun(options) {
-    (0, client_1.requireApiKey)();
-    const client = (0, client_1.createClient)();
+function buildAlertBody(options) {
     const body = {
         name: options.name,
         trigger_type: options.triggerType,
@@ -68,10 +67,15 @@ function createAlertRun(options) {
             throw new Error('--recipient must be a valid JSON array');
         }
     }
-    if (options.secret) {
+    if (options.secret !== undefined) {
         body.secret = options.secret;
     }
-    return client.post('/v0/alerts/', body);
+    return body;
+}
+function createAlertRun(options) {
+    (0, client_1.requireApiKey)();
+    const client = (0, client_1.createClient)();
+    return client.post('/v0/alerts/', buildAlertBody(options));
 }
 exports.alerts.command('create', {
     description: 'Create a new project alert',
@@ -102,30 +106,7 @@ exports.alerts.command('create', {
 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);
+    return client.put(`/v0/alerts/${encodeURIComponent(alertId)}`, buildAlertBody(options));
 }
 exports.alerts.command('update', {
     description: 'Update an existing alert',

package/dist/commands/contracts.d.ts

@@ -8,11 +8,23 @@ export interface CreateContractOptions {
     abi: string;
     events: string;
 }
+export declare function buildCreateContractBody(options: CreateContractOptions): {
+    address: string;
+    chain: number;
+    name: string;
+    abi: unknown;
+    events: unknown;
+};
 export declare function createContractRun(options: CreateContractOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;
 export interface UpdateContractOptions {
     name: string;
     abi: string;
     events: string;
 }
+export declare function buildUpdateContractBody(options: UpdateContractOptions): {
+    name: string;
+    abi: unknown;
+    events: unknown;
+};
 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, {}>>;

package/dist/commands/contracts.js

@@ -2,7 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.contracts = void 0;
 exports.listContractsRun = listContractsRun;
+exports.buildCreateContractBody = buildCreateContractBody;
 exports.createContractRun = createContractRun;
+exports.buildUpdateContractBody = buildUpdateContractBody;
 exports.updateContractRun = updateContractRun;
 exports.deleteContractRun = deleteContractRun;
 const incur_1 = require("incur");
@@ -24,9 +26,7 @@ exports.contracts.command('list', {
         return listContractsRun();
     },
 });
-function createContractRun(options) {
-    (0, client_1.requireApiKey)();
-    const client = (0, client_1.createClient)();
+function buildCreateContractBody(options) {
     let parsedAbi;
     try {
         parsedAbi = JSON.parse(options.abi);
@@ -41,13 +41,18 @@ function createContractRun(options) {
     catch {
         throw new Error('--events must be valid JSON');
     }
-    return client.post('/v0/contracts/', {
+    return {
         address: options.address,
         chain: options.chain,
         name: options.name,
         abi: parsedAbi,
         events: parsedEvents,
-    });
+    };
+}
+function createContractRun(options) {
+    (0, client_1.requireApiKey)();
+    const client = (0, client_1.createClient)();
+    return client.post('/v0/contracts/', buildCreateContractBody(options));
 }
 exports.contracts.command('create', {
     description: 'Register a new smart contract to track',
@@ -75,9 +80,7 @@ exports.contracts.command('create', {
         return createContractRun(options);
     },
 });
-function updateContractRun(chain, address, options) {
-    (0, client_1.requireApiKey)();
-    const client = (0, client_1.createClient)();
+function buildUpdateContractBody(options) {
     let parsedAbi;
     try {
         parsedAbi = JSON.parse(options.abi);
@@ -92,11 +95,16 @@ function updateContractRun(chain, address, options) {
     catch {
         throw new Error('--events must be valid JSON');
     }
-    return client.put(`/v0/contracts/${encodeURIComponent(chain)}/${encodeURIComponent(address)}`, {
+    return {
         name: options.name,
         abi: parsedAbi,
         events: parsedEvents,
-    });
+    };
+}
+function updateContractRun(chain, address, options) {
+    (0, client_1.requireApiKey)();
+    const client = (0, client_1.createClient)();
+    return client.put(`/v0/contracts/${encodeURIComponent(chain)}/${encodeURIComponent(address)}`, buildUpdateContractBody(options));
 }
 exports.contracts.command('update', {
     description: 'Update a tracked contract',

package/dist/commands/import.d.ts

@@ -4,4 +4,8 @@ export interface ImportWalletsOptions {
     addresses: string;
     writeKey: string;
 }
+export declare function buildImportBody(options: ImportWalletsOptions): {
+    addresses: any[];
+    writeKey: string;
+};
 export declare function importWalletsRun(options: ImportWalletsOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;

package/dist/commands/import.js

@@ -1,15 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.importCmd = void 0;
+exports.buildImportBody = buildImportBody;
 exports.importWalletsRun = importWalletsRun;
 const incur_1 = require("incur");
 const client_1 = require("../lib/client");
 exports.importCmd = incur_1.Cli.create('import', {
     description: 'Import commands — bulk import wallet addresses into your project',
 });
-function importWalletsRun(options) {
-    (0, client_1.requireApiKey)();
-    const client = (0, client_1.createClient)();
+function buildImportBody(options) {
     let parsedAddresses;
     try {
         parsedAddresses = JSON.parse(options.addresses);
@@ -20,10 +19,15 @@ function importWalletsRun(options) {
     catch {
         throw new Error('--addresses must be a valid JSON array of wallet address strings');
     }
-    return client.post('/v0/import/', {
+    return {
         addresses: parsedAddresses,
         writeKey: options.writeKey,
-    });
+    };
+}
+function importWalletsRun(options) {
+    (0, client_1.requireApiKey)();
+    const client = (0, client_1.createClient)();
+    return client.post('/v0/import/', buildImportBody(options));
 }
 exports.importCmd.command('wallets', {
     description: 'Bulk import wallet addresses into the project',

package/dist/commands/profiles.d.ts

@@ -3,8 +3,8 @@ export declare const profiles: Cli.Cli<{}, undefined, undefined>;
 export declare function getProfileRun(address: string, expand?: string): Promise<import("axios").AxiosResponse<any, any, {}>>;
 export interface SearchProfilesOptions {
     address?: string;
-    limit?: number;
-    offset?: number;
+    page?: number;
+    size?: number;
     orderBy?: string;
     orderDir?: string;
     expand?: string;
@@ -12,3 +12,23 @@ export interface SearchProfilesOptions {
     logic?: 'and' | 'or';
 }
 export declare function searchProfilesRun(options: SearchProfilesOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;
+export interface UpdateProfileOptions {
+    properties: string;
+}
+export declare function buildUpdateProfileBody(options: UpdateProfileOptions): Record<string, unknown>;
+export declare function updateProfileRun(address: string, options: UpdateProfileOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;
+export declare const profilesLabels: Cli.Cli<{}, undefined, undefined>;
+export interface CreateProfileLabelOptions {
+    tagId?: string;
+    value?: string;
+    chainId?: string;
+    labels?: string;
+}
+export declare function buildCreateLabelBody(options: CreateProfileLabelOptions): unknown;
+export declare function createProfileLabelRun(address: string, options: CreateProfileLabelOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;
+export interface DeleteProfileLabelOptions {
+    tagId: string;
+    chainId?: string;
+}
+export declare function buildDeleteLabelBody(options: DeleteProfileLabelOptions): Record<string, string>;
+export declare function deleteProfileLabelRun(address: string, options: DeleteProfileLabelOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;