@formo/cli 1.1.0 → 1.2.0

package/dist/commands/profiles.js

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.profilesLabels = exports.profilesProperties = exports.profiles = void 0;
 exports.getProfileRun = getProfileRun;
-exports.parseSearchConditions = parseSearchConditions;
+exports.parseSearchFilters = parseSearchFilters;
 exports.searchProfilesRun = searchProfilesRun;
 exports.buildUpdateProfileBody = buildUpdateProfileBody;
 exports.updateProfileRun = updateProfileRun;
@@ -16,6 +16,7 @@ exports.buildDeleteLabelBody = buildDeleteLabelBody;
 exports.deleteProfileLabelRun = deleteProfileLabelRun;
 const incur_1 = require("incur");
 const client_1 = require("../lib/client");
+const filters_1 = require("../lib/filters");
 const json_1 = require("../lib/json");
 exports.profiles = incur_1.Cli.create('profiles', {
     description: 'Wallet profile commands',
@@ -111,13 +112,23 @@ exports.profiles.command('get', {
         return getProfileRun(args.address, options);
     },
 });
-// Accepted first segments for a FilterCondition `field`, mirroring the API's
-// parseField(). A field whose prefix is not one of these is silently ignored
-// server-side (no error, no filtering — the search returns everything), so we
-// reject it client-side with an actionable message instead.
-const CONDITION_FIELD_PREFIXES = new Set([
-    'user',
-    'users',
+// Prefixes that may lead a user-surface `field` (e.g. `users.net_worth_usd`).
+// A bare name like `net_worth_usd` is silently ignored server-side (no error,
+// no filtering — the search returns everything), so we reject it client-side.
+const USER_FIELD_PREFIXES = new Set(['user', 'users']);
+// The four canonical resource filter fields. Resource identity lives in named
+// qualifier properties — never in the field path. The retired
+// identifier-in-path spellings (`chains.1.balance`, `apps.uniswap-v3.balance`,
+// `tokens.0x….balance`, `labels.vip`) are rejected by the API with a 400.
+const RESOURCE_FILTER_FIELDS = new Set([
+    'chains.balance',
+    'apps.balance',
+    'tokens.balance',
+    'labels.value',
+]);
+// Prefixes owned by the resource fields above. A field that leads with one of
+// these but is not an exact canonical path is a retired dynamic path.
+const RESOURCE_FIELD_PREFIXES = new Set([
     'chain',
     'chains',
     'app',
@@ -127,35 +138,138 @@ const CONDITION_FIELD_PREFIXES = new Set([
     'label',
     'labels',
 ]);
+const QUALIFIER_KEYS = [
+    'chain_id',
+    'app_id',
+    'token_address',
+    'tag_id',
+    'scope',
+];
+const FILTER_ENTRY_KEYS = new Set([
+    'field',
+    'op',
+    'value',
+    ...QUALIFIER_KEYS,
+]);
 /**
- * Parse and validate the --conditions JSON. Ensures it is an array of
- * `{ field, op, value }` objects whose `field` is a typed path (e.g.
- * `users.net_worth_usd`) — a bare name like `net_worth_usd` is silently
- * dropped by the API, so it is rejected here. Exported for unit testing.
+ * Enforce the per-field qualifier rules, mirroring the API's schema. Sending a
+ * qualifier the field does not accept — or omitting a required one — is a 400,
+ * so we fail here with a message that names the offending key.
  */
-function parseSearchConditions(raw) {
+function validateQualifiers(record, field) {
+    const present = (key) => record[key] !== undefined;
+    const required = (key) => {
+        if (!present(key)) {
+            throw new Error(`--filters: "${key}" is required for "${field}"`);
+        }
+    };
+    const forbidden = (keys) => {
+        for (const key of keys) {
+            if (present(key)) {
+                throw new Error(`--filters: "${key}" is not valid for "${field}"`);
+            }
+        }
+    };
+    switch (field) {
+        case 'chains.balance':
+            // chain_id optional — omit it to match any chain.
+            forbidden(['app_id', 'token_address', 'tag_id', 'scope']);
+            break;
+        case 'apps.balance':
+            required('app_id');
+            forbidden(['token_address', 'tag_id', 'scope']);
+            break;
+        case 'tokens.balance':
+            required('token_address');
+            required('scope');
+            if (record.scope !== 'any' && record.scope !== 'protocol') {
+                throw new Error(`--filters: "scope" must be "any" or "protocol"`);
+            }
+            // app_id identifies the protocol, so it is required by (and only by)
+            // scope: "protocol".
+            if (record.scope === 'protocol') {
+                required('app_id');
+            }
+            else {
+                forbidden(['app_id']);
+            }
+            forbidden(['tag_id']);
+            break;
+        case 'labels.value':
+            required('tag_id');
+            forbidden(['app_id', 'token_address', 'scope']);
+            break;
+        default:
+            // users.* — a user attribute carries no resource identity.
+            forbidden(QUALIFIER_KEYS);
+    }
+}
+/**
+ * Parse and validate the --filters JSON. Ensures it is an array of
+ * `{ field, op, value }` objects carrying a canonical `field` — either
+ * `users.{attribute}` or one of the four stable resource paths, with resource
+ * identity in named qualifier properties. Exported for unit testing.
+ */
+function parseSearchFilters(raw) {
     let parsed;
     try {
         parsed = JSON.parse(raw);
     }
     catch {
-        throw new Error('--conditions must be a valid JSON array of FilterCondition objects');
+        throw new Error('--filters must be a valid JSON array of FilterCondition objects');
     }
     if (!Array.isArray(parsed)) {
-        throw new Error('--conditions must be a valid JSON array of FilterCondition objects');
+        throw new Error('--filters must be a valid JSON array of FilterCondition objects');
     }
-    for (const cond of parsed) {
-        if (!cond || typeof cond !== 'object' || Array.isArray(cond)) {
-            throw new Error('--conditions: each entry must be an object with field, op, value');
+    for (const filter of parsed) {
+        if (!filter || typeof filter !== 'object' || Array.isArray(filter)) {
+            throw new Error('--filters: each entry must be an object with field, op, value');
         }
-        const field = cond.field;
+        const record = filter;
+        const field = record.field;
         if (typeof field !== 'string' || field.length === 0) {
-            throw new Error('--conditions: each entry must have a non-empty string "field"');
+            throw new Error('--filters: each entry must have a non-empty string "field"');
+        }
+        for (const key of Object.keys(record)) {
+            if (!FILTER_ENTRY_KEYS.has(key)) {
+                // `appId` was the pre-P-2387 spelling; the API now rejects unknown keys.
+                const hint = key === 'appId' ? ' — use the snake_case "app_id" qualifier' : '';
+                throw new Error(`--filters: unknown property "${key}"${hint}`);
+            }
+        }
+        const prefix = field.split('.')[0];
+        if (!RESOURCE_FILTER_FIELDS.has(field)) {
+            if (RESOURCE_FIELD_PREFIXES.has(prefix)) {
+                throw new Error(`--filters: field "${field}" is a retired identifier-in-path spelling. ` +
+                    'Use a stable path — chains.balance, apps.balance, tokens.balance, or labels.value — ' +
+                    'and move the identifier into a qualifier (chain_id, app_id, token_address, tag_id). ' +
+                    'The API rejects the old form with a 400.');
+            }
+            if (!field.includes('.') || !USER_FIELD_PREFIXES.has(prefix)) {
+                throw new Error(`--filters: field "${field}" must be a canonical path — either ` +
+                    'users.{attribute}, or one of chains.balance, apps.balance, tokens.balance, labels.value ' +
+                    '(a bare name is silently ignored by the API and returns the entire unfiltered dataset)');
+            }
+        }
+        validateQualifiers(record, field);
+        // The balance fields compare numerically; a stringified number is a 400.
+        if (field !== 'labels.value' &&
+            RESOURCE_FILTER_FIELDS.has(field) &&
+            typeof record.value !== 'number') {
+            throw new Error(`--filters: "value" must be a number for "${field}"`);
         }
-        if (!field.includes('.') || !CONDITION_FIELD_PREFIXES.has(field.split('.')[0])) {
-            throw new Error(`--conditions: field "${field}" must be a typed path — prefix it with ` +
-                'users., chains., apps., tokens., or labels. ' +
-                '(a bare name is silently ignored by the API and returns the entire unfiltered dataset)');
+        if (field === 'labels.value' && record.value === '') {
+            throw new Error(`--filters: "value" must be non-empty for "labels.value"`);
+        }
+        if (!(0, filters_1.isCanonicalFilterOperator)(record.op)) {
+            throw new Error('--filters: each entry must use a canonical "op" (eq, neq, gt, lt, gte, lte, in, nin, startsWith, endsWith, contains, notEmpty, or isEmpty)');
+        }
+        if ((0, filters_1.isEmptyMembershipArray)(record.value)) {
+            throw new Error('--filters: membership arrays cannot be empty');
+        }
+        if (!(0, filters_1.isValuelessFilterOperator)(record.op) &&
+            (record.value === undefined || record.value === null)) {
+            throw new Error('--filters: "value" is required for every operator except notEmpty/isEmpty');
         }
     }
     return parsed;
@@ -180,14 +294,14 @@ function searchProfilesRun(options) {
         params.expand = options.expand;
     addLifecycleThresholdParams(params, options);
     let body;
-    if (options.conditions) {
+    if (options.filters) {
         body = {
-            conditions: parseSearchConditions(options.conditions),
+            filters: parseSearchFilters(options.filters),
             logic: options.logic ?? 'and',
         };
     }
     // INTENTIONAL: the Formo search API is `GET /v0/profiles` with the
-    // `{ conditions, logic }` filter object in the *request body* (see
+    // `{ filters, logic }` filter object in the *request body* (see
     // docs.formo.so/api/profiles/search — it has a "Request Body (Filters)"
     // section under a GET endpoint). This GET-with-body shape is the
     // documented, server-supported contract. Do NOT "fix" it to POST — that
@@ -199,8 +313,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',
@@ -219,7 +343,7 @@ exports.profiles.command('search', {
             .describe('Field to sort by'),
         orderDir: incur_1.z.enum(['asc', 'desc']).optional().describe('Sort direction'),
         expand: incur_1.z.string().optional().describe('Comma-separated fields to expand'),
-        conditions: incur_1.z
+        filters: incur_1.z
             .string()
             .optional()
             .describe('JSON array of FilterCondition objects: [{"field","op","value"}]. ' +
@@ -227,16 +351,24 @@ exports.profiles.command('search', {
             'Profile: users.net_worth_usd, users.volume, users.revenue, users.points. ' +
             'Engagement: users.device, users.browser, users.os, users.location, users.lifecycle. ' +
             'Socials: users.ens, users.farcaster, users.lens, etc. ' +
-            'Chains: chains.balance or chains.{chain_id}.balance. ' +
-            'Apps: apps.{app_id}.balance. Tokens: tokens.{address}.balance ' +
-            '(optional "scope":"any"|"protocol" + "appId"). Labels: labels.{tag_id}. ' +
-            'op: eq, neq, gt, gte, lt, lte, in, nin, contains, notEmpty, isEmpty ' +
-            '(contains = substring, social fields only; notEmpty/isEmpty = value-less existence checks on string fields). ' +
-            'Long-form spellings (equals, notEquals, greater, greaterOrEqual, less, lessOrEqual, notIn, includes) are retired; the API rejects them with a 400 naming the token.'),
+            'Resource filters use a stable field plus named qualifiers: ' +
+            'chains.balance (+ optional "chain_id"); ' +
+            'apps.balance (+ "app_id", optional "chain_id"); ' +
+            'tokens.balance (+ "token_address", "scope":"any"|"protocol", "app_id" when scope is "protocol", optional "chain_id"); ' +
+            'labels.value (+ "tag_id", optional "chain_id"). ' +
+            'op: eq, neq, gt, gte, lt, lte, in, nin, contains, startsWith, endsWith, notEmpty, isEmpty. ' +
+            'Operator support is per field: the .balance fields take comparison operators only; ' +
+            'contains works on routable string attributes (users.device, users.os, users.referrer, users.utm_*, users.click_id — case-sensitive), ' +
+            'on social fields and on labels.value (case-insensitive); ' +
+            'startsWith/endsWith are routable string attributes only; ' +
+            'notEmpty/isEmpty are value-less existence checks on string fields; ' +
+            'users.lifecycle takes only eq and in. ' +
+            'Retired and rejected with a 400: identifier-in-path fields (chains.1.balance, apps.uniswap-v3.balance, tokens.0x….balance, labels.vip), ' +
+            'the "appId" spelling, and long-form operators (equals, notEquals, greater, greaterOrEqual, less, lessOrEqual, notIn, includes).'),
         logic: incur_1.z
             .enum(['and', 'or'])
             .optional()
-            .describe('Logic operator for combining conditions: "and" (default) or "or"'),
+            .describe('Logic operator for combining filters: "and" (default) or "or"'),
         ...lifecycleThresholdOptions,
     }),
     examples: [
@@ -251,14 +383,14 @@ exports.profiles.command('search', {
         },
         {
             options: {
-                conditions: '[{"field":"users.net_worth_usd","op":"gt","value":10000}]',
+                filters: '[{"field":"users.net_worth_usd","op":"gt","value":10000}]',
                 size: 20,
             },
             description: 'Search profiles with net worth > $10k',
         },
         {
             options: {
-                conditions: '[{"field":"users.net_worth_usd","op":"gt","value":10000},{"field":"users.volume","op":"gt","value":1000}]',
+                filters: '[{"field":"users.net_worth_usd","op":"gt","value":10000},{"field":"users.volume","op":"gt","value":1000}]',
                 logic: 'or',
                 size: 20,
             },
@@ -266,14 +398,21 @@ exports.profiles.command('search', {
         },
         {
             options: {
-                conditions: '[{"field":"chains.1.balance","op":"gt","value":1000}]',
+                filters: '[{"field":"chains.balance","op":"gt","value":1000,"chain_id":"1"}]',
                 size: 20,
             },
             description: 'Search profiles with > $1k balance on Ethereum (chain 1)',
         },
+        {
+            options: {
+                filters: '[{"field":"labels.value","op":"eq","value":"tier-1","tag_id":"vip"}]',
+                size: 20,
+            },
+            description: 'Search profiles carrying the vip label with value tier-1',
+        },
     ],
-    hint: 'Requires profiles:read scope on your API key. Filter "field" must be a typed path (e.g. users.net_worth_usd) — bare names are ignored by the API.',
-    run({ args: _args, options }) {
+    hint: 'Requires profiles:read scope on your API key. Filter "field" must be a canonical path (users.{attribute}, chains.balance, apps.balance, tokens.balance, labels.value) with resource identity in the chain_id/app_id/token_address/tag_id qualifiers — bare names are ignored by the API and identifier-in-path fields are rejected with a 400.',
+    run({ options }) {
         return searchProfilesRun(options);
     },
 });
@@ -364,15 +503,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;
+    filters: string;
 }
 export declare function buildCreateSegmentBody(options: CreateSegmentOptions): {
     title: string;
-    filterSets: any[];
+    filters: 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,48 +7,68 @@ exports.createSegmentRun = createSegmentRun;
 exports.deleteSegmentRun = deleteSegmentRun;
 const incur_1 = require("incur");
 const client_1 = require("../lib/client");
+const filters_1 = require("../lib/filters");
+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 }) {
         return listSegmentsRun(options);
     },
 });
+const SEGMENT_FILTER_KEYS = new Set(['field', 'op', 'value']);
 function buildCreateSegmentBody(options) {
-    let parsedFilterSets;
-    try {
-        parsedFilterSets = JSON.parse(options.filterSets);
-        if (!Array.isArray(parsedFilterSets)) {
-            throw new Error('not an array');
-        }
+    const filters = (0, json_1.parseJsonArray)(options.filters, '--filters');
+    if (filters.length === 0) {
+        throw new Error('--filters must contain at least one filter');
     }
-    catch {
-        throw new Error('--filter-sets must be a valid JSON array');
+    for (const filter of filters) {
+        if (!filter || typeof filter !== 'object' || Array.isArray(filter)) {
+            throw new Error('--filters must be a JSON array of {field, op, value} objects');
+        }
+        const record = filter;
+        if (Object.keys(record).some((key) => !SEGMENT_FILTER_KEYS.has(key))) {
+            throw new Error('--filters entries may only contain field, op, and value');
+        }
+        if (typeof record.field !== 'string' || record.field.length === 0) {
+            throw new Error('--filters: each entry requires a non-empty string "field"');
+        }
+        if (!(0, filters_1.isCanonicalFilterOperator)(record.op)) {
+            throw new Error('--filters: each entry requires a canonical "op"');
+        }
+        if ((0, filters_1.isEmptyMembershipArray)(record.value)) {
+            throw new Error('--filters: membership arrays cannot be empty');
+        }
+        if (!(0, filters_1.isValuelessFilterOperator)(record.op) &&
+            (record.value === undefined ||
+                record.value === null ||
+                !(0, filters_1.isCanonicalFilterValue)(record.value))) {
+            throw new Error('--filters: "value" is required for every operator except notEmpty/isEmpty');
+        }
+        if (record.value !== undefined &&
+            record.value !== null &&
+            !(0, filters_1.isCanonicalFilterValue)(record.value)) {
+            throw new Error('--filters: "value" must be a string, number, boolean, or string/number array');
+        }
+        if ((0, filters_1.hasTinybirdMembershipDelimiter)(record.value)) {
+            throw new Error('--filters: array string members cannot contain "|" because it is the Tinybird membership separator');
+        }
     }
     return {
         title: options.title,
-        filterSets: parsedFilterSets,
+        filters,
     };
 }
 function createSegmentRun(options) {
@@ -60,15 +80,15 @@ exports.segments.command('create', {
     description: 'Create a new user segment',
     options: incur_1.z.object({
         title: incur_1.z.string().describe('Segment title'),
-        filterSets: incur_1.z
+        filters: incur_1.z
             .string()
-            .describe('JSON array of filter set strings defining the segment'),
+            .describe('JSON array of canonical filter objects: [{"field","op","value"}]. Array string members cannot contain "|".'),
     }),
     examples: [
         {
             options: {
                 title: 'Whales',
-                filterSets: '["net_worth_usd > 100000"]',
+                filters: '[{"field":"net_worth_usd","op":"gt","value":"100000"}]',
             },
             description: 'Create a high-value segment',
         },

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)());
 }