@formo/cli 1.1.0 → 1.1.1

package/dist/commands/import.js

@@ -10,6 +10,9 @@ exports.importCmd = incur_1.Cli.create('import', {
     description: 'Import commands — bulk import wallet addresses into your project',
 });
 function buildImportBody(options) {
+    if (options.rows && options.addresses) {
+        throw new Error('Provide only one of --addresses or --rows');
+    }
     if (options.rows) {
         const rows = (0, json_1.parseJsonArrayOfObjects)(options.rows, '--rows');
         const addresses = rows.map((row) => row.address);

package/dist/commands/profiles.d.ts

@@ -12,7 +12,7 @@ export interface LifecycleThresholdOptions {
 export interface GetProfileOptions extends LifecycleThresholdOptions {
     expand?: string;
 }
-export declare function getProfileRun(address: string, optionsOrExpand?: GetProfileOptions | string): Promise<import("axios").AxiosResponse<any, any, {}>>;
+export declare function getProfileRun(address: string, optionsOrExpand?: GetProfileOptions | string): Promise<unknown>;
 export interface SearchProfilesOptions extends LifecycleThresholdOptions {
     address?: string;
     search?: string;
@@ -31,17 +31,17 @@ export interface SearchProfilesOptions extends LifecycleThresholdOptions {
  * 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 declare function searchProfilesRun(options: SearchProfilesOptions): Promise<unknown>;
 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 function updateProfileRun(address: string, options: UpdateProfileOptions): Promise<unknown>;
 export interface BatchUpdateProfilesOptions {
     rows: string;
 }
 export declare function buildBatchUpdateProfilesBody(options: BatchUpdateProfilesOptions): Record<string, unknown>[];
-export declare function batchUpdateProfilesRun(options: BatchUpdateProfilesOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;
+export declare function batchUpdateProfilesRun(options: BatchUpdateProfilesOptions): Promise<unknown>;
 export declare const profilesProperties: Cli.Cli<{}, undefined, undefined>;
 export declare const profilesLabels: Cli.Cli<{}, undefined, undefined>;
 export interface CreateProfileLabelOptions {
@@ -53,15 +53,15 @@ export interface CreateProfileLabelOptions {
     labels?: string;
 }
 export declare function buildCreateLabelBody(options: CreateProfileLabelOptions): unknown;
-export declare function createProfileLabelRun(address: string, options: CreateProfileLabelOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;
+export declare function createProfileLabelRun(address: string, options: CreateProfileLabelOptions): Promise<unknown>;
 export interface BatchCreateProfileLabelsOptions {
     labels: string;
 }
 export declare function buildBatchCreateLabelsBody(options: BatchCreateProfileLabelsOptions): Record<string, unknown>[];
-export declare function batchCreateProfileLabelsRun(options: BatchCreateProfileLabelsOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;
+export declare function batchCreateProfileLabelsRun(options: BatchCreateProfileLabelsOptions): Promise<unknown>;
 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, {}>>;
+export declare function deleteProfileLabelRun(address: string, options: DeleteProfileLabelOptions): Promise<unknown>;

package/dist/commands/profiles.js

@@ -199,8 +199,18 @@ exports.profiles.command('search', {
     options: incur_1.z.object({
         address: incur_1.z.string().optional().describe('Filter by wallet address'),
         search: incur_1.z.string().optional().describe('Free-text search across address and identity fields'),
-        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 1000)'),
+        page: incur_1.z.coerce
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe('Page number (1-indexed, default 1)'),
+        size: incur_1.z.coerce
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe('Page size (default 100, max 1000)'),
         orderBy: incur_1.z
             .enum([
             'last_onchain',
@@ -273,7 +283,7 @@ exports.profiles.command('search', {
         },
     ],
     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 }) {
+    run({ options }) {
         return searchProfilesRun(options);
     },
 });
@@ -364,15 +374,16 @@ exports.profilesLabels = incur_1.Cli.create('labels', {
 });
 function buildCreateLabelBody(options) {
     if (options.labels) {
-        try {
-            const parsed = JSON.parse(options.labels);
-            if (!Array.isArray(parsed) || parsed.length === 0)
-                throw new Error('not a non-empty array');
-            return parsed;
+        const parsed = (0, json_1.parseJsonArrayOfObjects)(options.labels, '--labels');
+        if (parsed.length === 0) {
+            throw new Error('--labels must contain at least one item');
         }
-        catch {
-            throw new Error('--labels must be a non-empty JSON array of UserLabelInput objects');
+        for (const label of parsed) {
+            if (typeof label.tag_id !== 'string' || label.tag_id.length === 0) {
+                throw new Error('--labels entries must each include a non-empty string tag_id');
+            }
         }
+        return parsed;
     }
     if (options.tagId) {
         const single = { tag_id: options.tagId };

package/dist/commands/query.d.ts

@@ -1,3 +1,3 @@
 import { Cli } from 'incur';
 export declare const query: Cli.Cli<{}, undefined, undefined>;
-export declare function queryRunRun(sql: string): Promise<import("axios").AxiosResponse<any, any, {}>>;
+export declare function queryRunRun(sql: string): Promise<unknown>;

package/dist/commands/segments.d.ts

@@ -1,17 +1,15 @@
 import { Cli } from 'incur';
+import { type PaginationOptions } from '../lib/pagination';
+export type { PaginationOptions };
 export declare const segments: Cli.Cli<{}, undefined, undefined>;
-export interface PaginationOptions {
-    page?: number;
-    size?: number;
-}
-export declare function listSegmentsRun(options?: PaginationOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;
+export declare function listSegmentsRun(options?: PaginationOptions): Promise<unknown>;
 export interface CreateSegmentOptions {
     title: string;
     filterSets: string;
 }
 export declare function buildCreateSegmentBody(options: CreateSegmentOptions): {
     title: string;
-    filterSets: any[];
+    filterSets: unknown[];
 };
-export declare function createSegmentRun(options: CreateSegmentOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;
-export declare function deleteSegmentRun(segmentId: string): Promise<import("axios").AxiosResponse<any, any, {}>>;
+export declare function createSegmentRun(options: CreateSegmentOptions): Promise<unknown>;
+export declare function deleteSegmentRun(segmentId: string): Promise<unknown>;

package/dist/commands/segments.js

@@ -7,28 +7,20 @@ exports.createSegmentRun = createSegmentRun;
 exports.deleteSegmentRun = deleteSegmentRun;
 const incur_1 = require("incur");
 const client_1 = require("../lib/client");
+const json_1 = require("../lib/json");
+const pagination_1 = require("../lib/pagination");
 exports.segments = incur_1.Cli.create('segments', {
     description: 'User segment commands — create, list, and delete audience segments',
 });
-function buildPaginationParams(options = {}) {
-    const params = {};
-    if (options.page !== undefined)
-        params.page = options.page;
-    if (options.size !== undefined)
-        params.size = options.size;
-    return params;
-}
+// ── List segments ──
 function listSegmentsRun(options = {}) {
     (0, client_1.requireApiKey)();
     const client = (0, client_1.createClient)();
-    return client.get('/v0/segments/', { params: buildPaginationParams(options) });
+    return client.get('/v0/segments/', { params: (0, pagination_1.buildPaginationParams)(options) });
 }
 exports.segments.command('list', {
     description: 'List all user segments 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 segments' }],
     hint: 'Requires segments:read scope on your API key.',
     run({ options }) {
@@ -36,15 +28,9 @@ exports.segments.command('list', {
     },
 });
 function buildCreateSegmentBody(options) {
-    let parsedFilterSets;
-    try {
-        parsedFilterSets = JSON.parse(options.filterSets);
-        if (!Array.isArray(parsedFilterSets)) {
-            throw new Error('not an array');
-        }
-    }
-    catch {
-        throw new Error('--filter-sets must be a valid JSON array');
+    const parsedFilterSets = (0, json_1.parseJsonArray)(options.filterSets, '--filter-sets');
+    if (parsedFilterSets.some((item) => typeof item !== 'string')) {
+        throw new Error('--filter-sets must be a JSON array of strings');
     }
     return {
         title: options.title,

package/dist/index.js

@@ -15,6 +15,11 @@ const segments_1 = require("./commands/segments");
 const client_1 = require("./lib/client");
 const config_1 = require("./lib/config");
 const ui_1 = require("./lib/ui");
+// Single source of truth for --version; a hardcoded literal here drifted
+// from package.json more than once. package.json sits outside rootDir, so
+// use require() rather than an import (tsc would widen the output layout).
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { version: VERSION } = require("../package.json");
 const DASHBOARD_URL = "https://app.formo.so";
 const DOCS_URL = "https://docs.formo.so";
 function loginGuide() {
@@ -43,23 +48,28 @@ async function validateAndFetchWorkspace(apiKey) {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({ apiKey }),
+            // fetch has no default timeout — without this, login can hang forever.
+            signal: AbortSignal.timeout(10000),
         });
+        // The server answered and rejected the key — distinct from "couldn't
+        // reach the server", so login can refuse to save a known-bad key.
         if (!res.ok)
-            return null;
+            return { kind: "invalid" };
         const body = (await res.json());
         if (!body.validated)
-            return null;
+            return { kind: "invalid" };
         return {
+            kind: "valid",
             workspace: body.details,
             projectId: body.scopes?.project_id ?? "",
         };
     }
     catch {
-        return null;
+        return { kind: "unreachable" };
     }
 }
 const cli = incur_1.Cli.create("formo", {
-    version: "1.0.1",
+    version: VERSION,
     description: "Formo API CLI — Web3 analytics from the terminal",
     sync: {
         suggestions: [
@@ -106,23 +116,27 @@ cli.command("login", {
         if (isTTY) {
             process.stderr.write("\n" + ui_1.color.dim("Validating API key…") + "\n");
         }
-        const workspaceInfo = await validateAndFetchWorkspace(args.apiKey);
-        // Save key + workspace info (save even if validation fails — user might be offline)
-        // Only include workspace/projectId when present so offline logins don't wipe existing values
+        const result = await validateAndFetchWorkspace(args.apiKey);
+        // The server explicitly rejected the key — refuse to save it. Saving a
+        // known-bad key just defers the failure to the user's next command.
+        if (result.kind === "invalid") {
+            throw new Error("API key was rejected by the Formo API (invalid or revoked). " +
+                "Check the key and try again, or create a new one at " +
+                `${DASHBOARD_URL} under Settings → API.`);
+        }
+        // Save the key. Offline (unreachable) logins still save — the user may
+        // simply have no network right now. Only include workspace/projectId
+        // when validated so offline logins don't wipe existing values, and only
+        // a non-empty projectId so an unscoped key doesn't clear a stored one.
+        const workspaceInfo = result.kind === "valid" ? result : undefined;
         (0, config_1.saveConfig)({
             apiKey: args.apiKey,
-            ...(workspaceInfo?.workspace !== undefined && {
-                workspace: workspaceInfo.workspace,
-            }),
-            ...(workspaceInfo?.projectId !== undefined && {
-                projectId: workspaceInfo.projectId,
-            }),
+            ...(workspaceInfo && { workspace: workspaceInfo.workspace }),
+            ...(workspaceInfo?.projectId && { projectId: workspaceInfo.projectId }),
         });
         // Show feedback in human mode
         if (isTTY) {
-            const masked = args.apiKey.length > 12
-                ? args.apiKey.slice(0, 8) + "…" + args.apiKey.slice(-4)
-                : "***";
+            const masked = (0, ui_1.maskKey)(args.apiKey);
             if (workspaceInfo) {
                 process.stderr.write((0, ui_1.success)("API key validated and saved!") +
                     "\n" +
@@ -133,7 +147,7 @@ cli.command("login", {
                     (workspaceInfo.projectId
                         ? (0, ui_1.info)(`Project: ${ui_1.color.dim(workspaceInfo.projectId)}`) + "\n"
                         : "") +
-                    (0, ui_1.info)(`Config: ${ui_1.color.dim("~/.config/formo/config.json")}`) +
+                    (0, ui_1.info)(`Config: ${ui_1.color.dim((0, config_1.getConfigFile)())}`) +
                     "\n\n" +
                     ui_1.color.dim("You can now use all formo commands.") +
                     "\n" +
@@ -147,9 +161,9 @@ cli.command("login", {
                     "\n" +
                     (0, ui_1.info)(`Key: ${ui_1.color.dim(masked)}`) +
                     "\n" +
-                    (0, ui_1.info)(`Config: ${ui_1.color.dim("~/.config/formo/config.json")}`) +
+                    (0, ui_1.info)(`Config: ${ui_1.color.dim((0, config_1.getConfigFile)())}`) +
                     "\n" +
-                    ui_1.color.dim("The API might be unreachable. Your key is saved and will be used for requests.") +
+                    ui_1.color.dim("The API was unreachable. Your key is saved and will be used for requests.") +
                     "\n\n");
             }
         }
@@ -157,7 +171,7 @@ cli.command("login", {
             ok: true,
             message: workspaceInfo
                 ? "API key validated and saved"
-                : "API key saved (not validated)",
+                : "API key saved (API unreachable, not validated)",
             workspace: workspaceInfo?.workspace ?? null,
             projectId: workspaceInfo?.projectId ?? null,
         };
@@ -174,7 +188,7 @@ cli.command("logout", {
             if (hadKey) {
                 process.stderr.write((0, ui_1.success)("Logged out successfully.") +
                     "\n" +
-                    (0, ui_1.info)("API key removed from ~/.config/formo/config.json") +
+                    (0, ui_1.info)(`API key removed from ${(0, config_1.getConfigFile)()}`) +
                     "\n");
             }
             else {
@@ -208,9 +222,7 @@ cli.command("status", {
         if (process.stdout.isTTY) {
             process.stderr.write("\n");
             if (apiKey) {
-                const masked = apiKey.length > 12
-                    ? apiKey.slice(0, 8) + "…" + apiKey.slice(-4)
-                    : "***";
+                const masked = (0, ui_1.maskKey)(apiKey);
                 process.stderr.write((0, ui_1.success)("Authenticated") +
                     "\n" +
                     (0, ui_1.info)(`Key: ${ui_1.color.dim(masked)}`) +
@@ -237,7 +249,7 @@ cli.command("status", {
             source: apiKey ? source : null,
             workspace: config.workspace ?? null,
             projectId: config.projectId ?? null,
-            configFile: config.apiKey ? "~/.config/formo/config.json" : null,
+            configFile: config.apiKey ? (0, config_1.getConfigFile)() : null,
         };
     },
 });
@@ -254,7 +266,8 @@ cli.command(segments_1.segments);
 cli.command(import_1.importCmd);
 // Show banner when run with no args (root help)
 const args = process.argv.slice(2);
-const isRootHelp = args.length === 0 || (args.length === 1 && args[0] === "--help");
+const isRootHelp = args.length === 0 ||
+    (args.length === 1 && (args[0] === "--help" || args[0] === "-h"));
 if (isRootHelp && process.stdout.isTTY) {
     process.stderr.write((0, ui_1.banner)());
 }

package/dist/lib/client.d.ts

@@ -1,4 +1,4 @@
-import { AxiosError } from 'axios';
+import { AxiosError, type AxiosInstance, type AxiosRequestConfig } from 'axios';
 export declare const DEFAULT_API_BASE_URL = "https://api.formo.so";
 export declare const DEFAULT_EVENTS_BASE_URL = "https://events.formo.so";
 export declare function getApiBaseUrl(): string;
@@ -32,7 +32,22 @@ export interface ClientOptions {
     baseURL?: string;
     apiKey?: string;
 }
-declare function createClient(options?: ClientOptions): import("axios").AxiosInstance;
-export declare function createEventsClient(writeKey: string): import("axios").AxiosInstance;
+/**
+ * The response interceptor below unwraps every response to its body
+ * (`res.data`), so the raw AxiosInstance types would lie — they promise
+ * `AxiosResponse<T>` while the runtime value is the body itself. This
+ * interface states what actually comes back.
+ */
+export interface FormoClient {
+    get(url: string, config?: AxiosRequestConfig): Promise<unknown>;
+    post(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<unknown>;
+    put(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<unknown>;
+    patch(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<unknown>;
+    delete(url: string, config?: AxiosRequestConfig): Promise<unknown>;
+    request(config: AxiosRequestConfig): Promise<unknown>;
+    defaults: AxiosInstance['defaults'];
+}
+declare function createClient(options?: ClientOptions): FormoClient;
+export declare function createEventsClient(writeKey: string): FormoClient;
 export declare function requireApiKey(): void;
 export { createClient };

package/dist/lib/client.js

@@ -38,7 +38,9 @@ function parseApiError(error) {
         parts.push(`Param: ${apiError.param}`);
     if (apiError?.details && Object.keys(apiError.details).length > 0) {
         const details = Object.entries(apiError.details)
-            .map(([key, value]) => `${key}: ${String(value)}`)
+            .map(([key, value]) => `${key}: ${typeof value === 'object' && value !== null
+            ? JSON.stringify(value)
+            : String(value)}`)
             .join('; ');
         parts.push(`Details: ${details}`);
     }
@@ -57,17 +59,24 @@ function parseApiError(error) {
 function createClient(options = {}) {
     const apiKey = options.apiKey ?? (0, config_1.getApiKey)();
     const baseURL = options.baseURL ?? getApiBaseUrl();
+    // Fail here, not with a server-side 401: every authenticated command needs
+    // a key, and this guard catches call sites that forget requireApiKey().
+    if (!apiKey) {
+        throw new Error('No API key configured. Run `formo login <apiKey>` or set FORMO_API_KEY env var.');
+    }
     const instance = axios_1.default.create({
         baseURL,
         timeout: 30000,
         headers: {
             'Content-Type': 'application/json',
-            ...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}),
+            Authorization: `Bearer ${apiKey}`,
         },
     });
     instance.interceptors.response.use((res) => res.data, (error) => {
         throw parseApiError(error);
     });
+    // The interceptor changes what the promise resolves to; the cast makes the
+    // public type match the runtime behavior (see FormoClient above).
     return instance;
 }
 function createEventsClient(writeKey) {

package/dist/lib/config.d.ts

@@ -1,3 +1,4 @@
+export declare function getConfigFile(): string;
 export interface FormoConfig {
     apiKey?: string;
     workspace?: string;

package/dist/lib/config.js

@@ -3,6 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.getConfigFile = getConfigFile;
 exports.readConfig = readConfig;
 exports.saveConfig = saveConfig;
 exports.clearConfig = clearConfig;
@@ -10,12 +11,24 @@ exports.getApiKey = getApiKey;
 const fs_1 = __importDefault(require("fs"));
 const os_1 = __importDefault(require("os"));
 const path_1 = __importDefault(require("path"));
-const CONFIG_DIR = path_1.default.join(os_1.default.homedir(), '.config', 'formo');
-const CONFIG_FILE = path_1.default.join(CONFIG_DIR, 'config.json');
+// FORMO_CONFIG_DIR lets tests (and users) redirect config away from the real
+// ~/.config/formo — resolved lazily so a test can set it after import.
+function configDir() {
+    return (process.env.FORMO_CONFIG_DIR ?? path_1.default.join(os_1.default.homedir(), '.config', 'formo'));
+}
+function getConfigFile() {
+    return path_1.default.join(configDir(), 'config.json');
+}
 function readConfig() {
     try {
-        const raw = fs_1.default.readFileSync(CONFIG_FILE, 'utf-8');
-        return JSON.parse(raw);
+        const raw = fs_1.default.readFileSync(getConfigFile(), 'utf-8');
+        const parsed = JSON.parse(raw);
+        // JSON.parse happily returns null/"abc"/[1] — treat anything that isn't a
+        // plain object as an empty config instead of crashing later callers.
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            return {};
+        }
+        return parsed;
     }
     catch {
         return {};
@@ -29,26 +42,27 @@ function saveConfig(updates) {
     // tool, another app under ~/.config) keeps its old, possibly
     // group/world-readable perms — leaking the plaintext API key on a
     // multi-user host. chmod unconditionally so 0o700/0o600 always holds.
-    fs_1.default.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
-    fs_1.default.chmodSync(CONFIG_DIR, 0o700);
-    fs_1.default.writeFileSync(CONFIG_FILE, JSON.stringify(merged, null, 2), {
+    fs_1.default.mkdirSync(configDir(), { recursive: true, mode: 0o700 });
+    fs_1.default.chmodSync(configDir(), 0o700);
+    fs_1.default.writeFileSync(getConfigFile(), JSON.stringify(merged, null, 2), {
         mode: 0o600,
     });
-    fs_1.default.chmodSync(CONFIG_FILE, 0o600);
+    fs_1.default.chmodSync(getConfigFile(), 0o600);
 }
 function clearConfig() {
     try {
-        if (fs_1.default.existsSync(CONFIG_FILE)) {
-            fs_1.default.writeFileSync(CONFIG_FILE, JSON.stringify({}, null, 2), {
-                mode: 0o600,
-            });
-            // Same create-only-mode caveat as saveConfig: enforce 0o600 on the
-            // already-existing file so the cleared config can't be left readable.
-            fs_1.default.chmodSync(CONFIG_FILE, 0o600);
-        }
+        fs_1.default.writeFileSync(getConfigFile(), JSON.stringify({}, null, 2), {
+            mode: 0o600,
+        });
+        // Same create-only-mode caveat as saveConfig: enforce 0o600 on the
+        // already-existing file so the cleared config can't be left readable.
+        fs_1.default.chmodSync(getConfigFile(), 0o600);
     }
-    catch {
-        // Ignore errors if file doesn't exist
+    catch (err) {
+        // Nothing to clear is fine; a real write failure (EACCES, EROFS) must
+        // surface so `formo logout` can't claim success while the key remains.
+        if (err.code !== 'ENOENT')
+            throw err;
     }
 }
 function getApiKey() {

package/dist/lib/pagination.d.ts

@@ -0,0 +1,14 @@
+import { z } from 'incur';
+export interface PaginationOptions {
+    page?: number;
+    size?: number;
+}
+/**
+ * Shared zod fragments for paginated list commands.
+ * Spread into a command's options: `z.object({ ...paginationOptionsSchema })`.
+ */
+export declare const paginationOptionsSchema: {
+    page: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+    size: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+};
+export declare function buildPaginationParams(options?: PaginationOptions): Record<string, number>;

package/dist/lib/pagination.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.paginationOptionsSchema = void 0;
+exports.buildPaginationParams = buildPaginationParams;
+const incur_1 = require("incur");
+/**
+ * Shared zod fragments for paginated list commands.
+ * Spread into a command's options: `z.object({ ...paginationOptionsSchema })`.
+ */
+exports.paginationOptionsSchema = {
+    page: incur_1.z.coerce
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('Page number (1-indexed, default 1)'),
+    size: incur_1.z.coerce
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('Page size (default 100, max 200)'),
+};
+function buildPaginationParams(options = {}) {
+    const params = {};
+    if (options.page !== undefined)
+        params.page = options.page;
+    if (options.size !== undefined)
+        params.size = options.size;
+    return params;
+}

package/dist/lib/ui.d.ts

@@ -2,8 +2,9 @@
  * Terminal UI utilities for the Formo CLI.
  *
  * Uses raw ANSI escape codes (no dependencies) for coloring and styling.
- * Colors are automatically disabled when stdout is not a TTY (piped output, CI, etc.)
- * or when the NO_COLOR environment variable is set.
+ * All decorated output is written to stderr (stdout is reserved for command
+ * results), so color is keyed to stderr being a TTY. Disabled whenever the
+ * NO_COLOR environment variable is present (any value, per the spec).
  */
 export declare const color: {
     green: (t: string) => string;
@@ -20,12 +21,12 @@ export declare const color: {
 };
 /**
  * Returns the Formo ASCII art banner in green.
- * Only shown when stdout is a TTY.
+ * Only shown when stderr is a TTY.
  */
 export declare function banner(): string;
 export declare function success(message: string): string;
 export declare function error(message: string): string;
 export declare function warn(message: string): string;
 export declare function info(message: string): string;
-export declare function keyValue(key: string, value: string): string;
-export declare function heading(text: string): string;
+/** Mask an API key for display, keeping just enough to identify it. */
+export declare function maskKey(key: string): string;

package/dist/lib/ui.js

@@ -3,8 +3,9 @@
  * Terminal UI utilities for the Formo CLI.
  *
  * Uses raw ANSI escape codes (no dependencies) for coloring and styling.
- * Colors are automatically disabled when stdout is not a TTY (piped output, CI, etc.)
- * or when the NO_COLOR environment variable is set.
+ * All decorated output is written to stderr (stdout is reserved for command
+ * results), so color is keyed to stderr being a TTY. Disabled whenever the
+ * NO_COLOR environment variable is present (any value, per the spec).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.color = void 0;
@@ -13,10 +14,9 @@ exports.success = success;
 exports.error = error;
 exports.warn = warn;
 exports.info = info;
-exports.keyValue = keyValue;
-exports.heading = heading;
-const isTTY = process.stdout.isTTY === true;
-const noColor = !!process.env.NO_COLOR;
+exports.maskKey = maskKey;
+const isTTY = process.stderr.isTTY === true;
+const noColor = process.env.NO_COLOR !== undefined;
 /** Whether color output is enabled */
 const colorEnabled = isTTY && !noColor;
 // ── ANSI helpers ──
@@ -47,7 +47,7 @@ const LOGO_LINES = [
 ];
 /**
  * Returns the Formo ASCII art banner in green.
- * Only shown when stdout is a TTY.
+ * Only shown when stderr is a TTY.
  */
 function banner() {
     if (!isTTY)
@@ -71,9 +71,7 @@ function info(message) {
     return `${exports.color.cyan('ℹ')} ${message}`;
 }
 // ── Formatting helpers ──
-function keyValue(key, value) {
-    return `${exports.color.dim(key + ':')} ${value}`;
-}
-function heading(text) {
-    return exports.color.boldGreen(text);
+/** Mask an API key for display, keeping just enough to identify it. */
+function maskKey(key) {
+    return key.length > 12 ? key.slice(0, 8) + '…' + key.slice(-4) : '***';
 }