npm - @respan/cli - Versions diffs - 0.2.0 → 0.3.1 - Mend

@respan/cli 0.2.0 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (14) hide show

package/dist/commands/auth/login.d.ts +2 -1
package/dist/commands/auth/login.js +128 -10
package/dist/commands/auth/status.js +1 -1
package/dist/commands/logs/list.d.ts +3 -0
package/dist/commands/logs/list.js +30 -22
package/dist/commands/logs/summary.d.ts +3 -0
package/dist/commands/logs/summary.js +24 -2
package/dist/commands/traces/list.js +22 -12
package/dist/lib/auth.d.ts +2 -0
package/dist/lib/auth.js +2 -1
package/dist/lib/filters.d.ts +24 -0
package/dist/lib/filters.js +100 -0
package/oclif.manifest.json +59 -12
package/package.json +1 -1

package/dist/commands/auth/login.d.ts CHANGED Viewed

@@ -4,7 +4,8 @@ export default class AuthLogin extends BaseCommand {
     static flags: {
         'api-key': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'profile-name': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
-        'base-url': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        'base-url': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        enterprise: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         profile: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         csv: import("@oclif/core/interfaces").BooleanFlag<boolean>;

package/dist/commands/auth/login.js CHANGED Viewed

@@ -1,26 +1,144 @@
 import { Flags } from '@oclif/core';
-import { password } from '@inquirer/prompts';
+import { select, password } from '@inquirer/prompts';
+import * as http from 'node:http';
+import * as open from 'node:child_process';
 import { BaseCommand } from '../../lib/base-command.js';
-import { setCredential } from '../../lib/config.js';
+import { setCredential, setActiveProfile } from '../../lib/config.js';
 import { printLoginSuccess } from '../../lib/banner.js';
+import { DEFAULT_BASE_URL, ENTERPRISE_BASE_URL } from '../../lib/auth.js';
+const CALLBACK_PORT = 18392;
+const CALLBACK_PATH = '/callback';
+const LOGIN_TIMEOUT_MS = 120_000;
+const LOGIN_URL_BASE = 'https://platform.respan.ai/login';
+const ENTERPRISE_LOGIN_URL_BASE = 'https://enterprise.respan.ai/login';
+function openBrowser(url) {
+    const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
+    open.exec(`${cmd} "${url}"`);
+}
+function successHtml() {
+    return `<!DOCTYPE html>
+<html>
+<head><meta charset="utf-8"><title>Respan CLI</title>
+<style>body{font-family:-apple-system,system-ui,sans-serif;display:flex;align-items:center;justify-content:center;height:100vh;margin:0;background:#0a0a0f;color:#fff}
+.card{text-align:center;padding:2rem}.check{font-size:3rem;margin-bottom:1rem;color:#6483F0}p{color:#aaa;margin-top:0.5rem}</style></head>
+<body><div class="card"><div class="check">&#10003;</div><h2>Login successful!</h2><p>You can close this window and return to the terminal.</p></div></body></html>`;
+}
+function errorHtml(msg) {
+    return `<!DOCTYPE html>
+<html>
+<head><meta charset="utf-8"><title>Respan CLI</title>
+<style>body{font-family:-apple-system,system-ui,sans-serif;display:flex;align-items:center;justify-content:center;height:100vh;margin:0;background:#0a0a0f;color:#fff}
+.card{text-align:center;padding:2rem}.icon{font-size:3rem;margin-bottom:1rem;color:#f06464}p{color:#aaa;margin-top:0.5rem}</style></head>
+<body><div class="card"><div class="icon">&#10007;</div><h2>Login failed</h2><p>${msg}</p></div></body></html>`;
+}
+function waitForBrowserLogin(enterprise) {
+    return new Promise((resolve, reject) => {
+        const server = http.createServer((req, res) => {
+            const url = new URL(req.url || '/', `http://localhost:${CALLBACK_PORT}`);
+            if (url.pathname !== CALLBACK_PATH) {
+                res.writeHead(404);
+                res.end('Not found');
+                return;
+            }
+            const token = url.searchParams.get('token');
+            const refreshToken = url.searchParams.get('refresh_token');
+            const email = url.searchParams.get('email') || undefined;
+            if (!token || !refreshToken) {
+                res.writeHead(400, { 'Content-Type': 'text/html' });
+                res.end(errorHtml('Missing token. Please try again.'));
+                cleanup();
+                reject(new Error('Login callback missing token or refresh_token.'));
+                return;
+            }
+            res.writeHead(200, { 'Content-Type': 'text/html' });
+            res.end(successHtml());
+            cleanup();
+            resolve({ token, refreshToken, email });
+        });
+        const timeout = setTimeout(() => {
+            cleanup();
+            reject(new Error('Login timed out after 120 seconds. Please try again.'));
+        }, LOGIN_TIMEOUT_MS);
+        function cleanup() {
+            clearTimeout(timeout);
+            server.close();
+        }
+        server.on('error', (err) => {
+            if (err.code === 'EADDRINUSE') {
+                reject(new Error(`Port ${CALLBACK_PORT} is in use. Close the other process and try again.`));
+            }
+            else {
+                reject(err);
+            }
+        });
+        server.listen(CALLBACK_PORT, '127.0.0.1', () => {
+            const redirectUri = `http://localhost:${CALLBACK_PORT}${CALLBACK_PATH}`;
+            const loginUrlBase = enterprise ? ENTERPRISE_LOGIN_URL_BASE : LOGIN_URL_BASE;
+            const loginUrl = new URL(loginUrlBase);
+            loginUrl.searchParams.set('mode', 'cli');
+            loginUrl.searchParams.set('redirect_uri', redirectUri);
+            console.log('');
+            console.log('  Opening browser to log in...');
+            console.log(`  If the browser doesn't open, visit:`);
+            console.log(`  ${loginUrl.toString()}`);
+            console.log('');
+            console.log('  Waiting for login (timeout: 120s)...');
+            openBrowser(loginUrl.toString());
+        });
+    });
+}
 class AuthLogin extends BaseCommand {
     async run() {
         const { flags } = await this.parse(AuthLogin);
         this.globalFlags = flags;
-        let apiKey = flags['api-key'];
-        if (!apiKey) {
-            apiKey = await password({ message: 'Enter your Respan API key:' });
-        }
         const profile = flags['profile-name'] || 'default';
-        setCredential(profile, { type: 'api_key', apiKey, baseUrl: flags['base-url'] });
-        await printLoginSuccess(undefined, profile);
+        setActiveProfile(profile);
+        // Step 1: Determine environment (skip if --enterprise flag or --api-key with flag)
+        const enterprise = flags.enterprise || (!flags['api-key'] && await select({
+            message: 'Select your environment:',
+            choices: [
+                { name: 'Respan Platform', value: false },
+                { name: 'Enterprise', value: true },
+            ],
+        }));
+        const baseUrl = flags['base-url'] || (enterprise ? ENTERPRISE_BASE_URL : DEFAULT_BASE_URL);
+        // If --api-key passed directly, skip auth method prompt
+        if (flags['api-key']) {
+            setCredential(profile, { type: 'api_key', apiKey: flags['api-key'], baseUrl });
+            await printLoginSuccess(undefined, profile);
+            return;
+        }
+        // Step 2: Choose auth method
+        const method = await select({
+            message: 'How would you like to authenticate?',
+            choices: [
+                { name: 'Browser login (recommended)', value: 'browser' },
+                { name: 'API key', value: 'api_key' },
+            ],
+        });
+        if (method === 'api_key') {
+            const apiKey = await password({ message: 'Enter your Respan API key:' });
+            setCredential(profile, { type: 'api_key', apiKey, baseUrl });
+            await printLoginSuccess(undefined, profile);
+            return;
+        }
+        const result = await waitForBrowserLogin(enterprise);
+        setCredential(profile, {
+            type: 'jwt',
+            accessToken: result.token,
+            refreshToken: result.refreshToken,
+            email: result.email || '',
+            baseUrl,
+        });
+        await printLoginSuccess(result.email, profile);
     }
 }
 AuthLogin.description = 'Log in to Respan';
 AuthLogin.flags = {
     ...BaseCommand.baseFlags,
-    'api-key': Flags.string({ description: 'API key to store' }),
+    'api-key': Flags.string({ description: 'API key to store (skips interactive prompt)' }),
     'profile-name': Flags.string({ description: 'Profile name', default: 'default' }),
-    'base-url': Flags.string({ description: 'API base URL', default: 'https://api.respan.ai/api' }),
+    'base-url': Flags.string({ description: 'API base URL (auto-detected from login method if not set)' }),
+    enterprise: Flags.boolean({ description: 'Use enterprise SSO login', default: false }),
 };
 export default AuthLogin;

package/dist/commands/auth/status.js CHANGED Viewed

@@ -4,7 +4,7 @@ class AuthStatus extends BaseCommand {
     async run() {
         const { flags } = await this.parse(AuthStatus);
         this.globalFlags = flags;
-        const profile = getActiveProfile();
+        const profile = flags.profile || getActiveProfile();
         const cred = getCredential(profile);
         if (!cred) {
             this.log('Not authenticated. Run `respan auth login`.');

package/dist/commands/logs/list.d.ts CHANGED Viewed

@@ -8,6 +8,9 @@ export default class LogsList extends BaseCommand {
         'start-time': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'end-time': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         filter: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'all-envs': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'is-test': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'include-fields': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'api-key': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         profile: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         json: import("@oclif/core/interfaces").BooleanFlag<boolean>;

package/dist/commands/logs/list.js CHANGED Viewed

@@ -1,5 +1,6 @@
 import { Flags } from '@oclif/core';
 import { BaseCommand } from '../../lib/base-command.js';
+import { parseFilters, FILTER_SYNTAX_HELP, LOG_FIELDS_HELP, FILTER_EXAMPLES } from '../../lib/filters.js';
 import { extractPagination, formatPaginationInfo } from '../../lib/pagination.js';
 class LogsList extends BaseCommand {
     async run() {
@@ -7,27 +8,23 @@ class LogsList extends BaseCommand {
         this.globalFlags = flags;
         try {
             const client = this.getClient();
-            const params = {
-                page_size: flags.limit,
-                page: flags.page,
-            };
-            if (flags['sort-by'])
-                params.sort_by = flags['sort-by'];
-            if (flags['start-time'])
-                params.start_time = flags['start-time'];
-            if (flags['end-time'])
-                params.end_time = flags['end-time'];
-            if (flags.filter && flags.filter.length > 0)
-                params.filters = flags.filter;
-            // listSpans requires start_time, end_time, sort_by, operator
+            let filters;
+            if (flags.filter && flags.filter.length > 0) {
+                filters = parseFilters(flags.filter);
+            }
             const oneHourAgo = new Date(Date.now() - 60 * 60 * 1000).toISOString();
             const data = await this.spin('Fetching logs', () => client.logs.listSpans({
-                start_time: params.start_time || oneHourAgo,
-                end_time: params.end_time || new Date().toISOString(),
-                sort_by: params.sort_by || '-id',
+                start_time: flags['start-time'] || oneHourAgo,
+                end_time: flags['end-time'] || new Date().toISOString(),
+                sort_by: flags['sort-by'] || '-id',
                 operator: '',
-                page_size: params.page_size,
-                page: params.page,
+                page_size: flags.limit,
+                page: flags.page,
+                is_test: flags['is-test'],
+                all_envs: flags['all-envs'],
+                fetch_filters: 'false',
+                include_fields: flags['include-fields'],
+                filters,
             }));
             this.outputResult(data, ['id', 'model', 'prompt_tokens', 'completion_tokens', 'cost', 'latency', 'timestamp']);
             const pagination = extractPagination(data, flags.page);
@@ -38,14 +35,25 @@ class LogsList extends BaseCommand {
         }
     }
 }
-LogsList.description = 'List log spans';
+LogsList.description = `List and filter LLM request logs (spans).
+Supports pagination, sorting, time range, and server-side filtering.
+${FILTER_SYNTAX_HELP}
+${LOG_FIELDS_HELP}
+${FILTER_EXAMPLES}`;
 LogsList.flags = {
     ...BaseCommand.baseFlags,
-    limit: Flags.integer({ description: 'Number of results per page', default: 50 }),
+    limit: Flags.integer({ description: 'Number of results per page (max 1000)', default: 50 }),
     page: Flags.integer({ description: 'Page number', default: 1 }),
-    'sort-by': Flags.string({ description: 'Sort field' }),
+    'sort-by': Flags.string({ description: 'Sort field (prefix with - for descending, e.g. -cost, -latency)' }),
     'start-time': Flags.string({ description: 'Start time filter (ISO 8601)' }),
     'end-time': Flags.string({ description: 'End time filter (ISO 8601)' }),
-    filter: Flags.string({ description: 'Filter expression', multiple: true }),
+    filter: Flags.string({ description: 'Filter in field:operator:value format (repeatable)', multiple: true }),
+    'all-envs': Flags.string({ description: 'Include all environments (true/false)' }),
+    'is-test': Flags.string({ description: 'Filter by test (true) or production (false) environment' }),
+    'include-fields': Flags.string({ description: 'Comma-separated fields to include in response' }),
 };
 export default LogsList;

package/dist/commands/logs/summary.d.ts CHANGED Viewed

@@ -4,6 +4,9 @@ export default class LogsSummary extends BaseCommand {
     static flags: {
         'start-time': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         'end-time': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        filter: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'all-envs': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'is-test': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'api-key': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         profile: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         json: import("@oclif/core/interfaces").BooleanFlag<boolean>;

package/dist/commands/logs/summary.js CHANGED Viewed

@@ -1,12 +1,23 @@
 import { Flags } from '@oclif/core';
 import { BaseCommand } from '../../lib/base-command.js';
+import { parseFilters, FILTER_SYNTAX_HELP, LOG_FIELDS_HELP, FILTER_EXAMPLES } from '../../lib/filters.js';
 class LogsSummary extends BaseCommand {
     async run() {
         const { flags } = await this.parse(LogsSummary);
         this.globalFlags = flags;
         try {
             const client = this.getClient();
-            const data = await this.spin('Fetching summary', () => client.logs.getSpansSummary({ start_time: flags['start-time'], end_time: flags['end-time'] }));
+            let filters;
+            if (flags.filter && flags.filter.length > 0) {
+                filters = parseFilters(flags.filter);
+            }
+            const data = await this.spin('Fetching summary', () => client.logs.getSpansSummary({
+                start_time: flags['start-time'],
+                end_time: flags['end-time'],
+                is_test: flags['is-test'],
+                all_envs: flags['all-envs'],
+                filters,
+            }));
             this.log(JSON.stringify(data, null, 2));
         }
         catch (error) {
@@ -14,10 +25,21 @@ class LogsSummary extends BaseCommand {
         }
     }
 }
-LogsSummary.description = 'Get a summary of log spans for a time range';
+LogsSummary.description = `Get aggregated summary statistics for log spans in a time range.
+Returns total cost, total tokens, request count, and score summaries.
+${FILTER_SYNTAX_HELP}
+${LOG_FIELDS_HELP}
+${FILTER_EXAMPLES}`;
 LogsSummary.flags = {
     ...BaseCommand.baseFlags,
     'start-time': Flags.string({ description: 'Start time (ISO 8601)', required: true }),
     'end-time': Flags.string({ description: 'End time (ISO 8601)', required: true }),
+    filter: Flags.string({ description: 'Filter in field:operator:value format (repeatable)', multiple: true }),
+    'all-envs': Flags.string({ description: 'Include all environments (true/false)' }),
+    'is-test': Flags.string({ description: 'Filter by test (true) or production (false) environment' }),
 };
 export default LogsSummary;

package/dist/commands/traces/list.js CHANGED Viewed

@@ -1,5 +1,6 @@
 import { Flags } from '@oclif/core';
 import { BaseCommand } from '../../lib/base-command.js';
+import { parseFilters, FILTER_SYNTAX_HELP, TRACE_FIELDS_HELP, FILTER_EXAMPLES } from '../../lib/filters.js';
 import { extractPagination, formatPaginationInfo } from '../../lib/pagination.js';
 class TracesList extends BaseCommand {
     async run() {
@@ -7,21 +8,22 @@ class TracesList extends BaseCommand {
         this.globalFlags = flags;
         try {
             const client = this.getClient();
-            const params = {
+            let bodyFilters = {};
+            if (flags.filter && flags.filter.length > 0) {
+                bodyFilters = parseFilters(flags.filter);
+            }
+            const queryParams = {
                 page_size: flags.limit,
                 page: flags.page,
+                sort_by: flags['sort-by'],
             };
-            if (flags['sort-by'])
-                params.sort_by = flags['sort-by'];
             if (flags['start-time'])
-                params.start_time = flags['start-time'];
+                queryParams.start_time = flags['start-time'];
             if (flags['end-time'])
-                params.end_time = flags['end-time'];
+                queryParams.end_time = flags['end-time'];
             if (flags.environment)
-                params.environment = flags.environment;
-            if (flags.filter && flags.filter.length > 0)
-                params.filters = flags.filter;
-            const data = await this.spin('Fetching traces', () => client.traces.list(params));
+                queryParams.environment = flags.environment;
+            const data = await this.spin('Fetching traces', () => client.traces.list({ filters: bodyFilters }, { queryParams }));
             this.outputResult(data, [
                 'trace_unique_id', 'name', 'duration', 'span_count', 'total_cost', 'error_count', 'start_time',
             ]);
@@ -33,15 +35,23 @@ class TracesList extends BaseCommand {
         }
     }
 }
-TracesList.description = 'List traces';
+TracesList.description = `List and filter traces.
+A trace represents a complete workflow execution containing multiple spans.
+${FILTER_SYNTAX_HELP}
+${TRACE_FIELDS_HELP}
+${FILTER_EXAMPLES}`;
 TracesList.flags = {
     ...BaseCommand.baseFlags,
     limit: Flags.integer({ description: 'Number of results per page', default: 10 }),
     page: Flags.integer({ description: 'Page number', default: 1 }),
-    'sort-by': Flags.string({ description: 'Sort field', default: '-timestamp' }),
+    'sort-by': Flags.string({ description: 'Sort field (prefix with - for descending)', default: '-timestamp' }),
     'start-time': Flags.string({ description: 'Start time filter (ISO 8601)' }),
     'end-time': Flags.string({ description: 'End time filter (ISO 8601)' }),
     environment: Flags.string({ description: 'Environment filter' }),
-    filter: Flags.string({ description: 'Filter expression', multiple: true }),
+    filter: Flags.string({ description: 'Filter in field:operator:value format (repeatable)', multiple: true }),
 };
 export default TracesList;

package/dist/lib/auth.d.ts CHANGED Viewed

@@ -1,4 +1,6 @@
 import { Credential } from './config.js';
+export declare const DEFAULT_BASE_URL = "https://api.respan.ai";
+export declare const ENTERPRISE_BASE_URL = "https://endpoint.respan.ai";
 export interface AuthConfig {
     apiKey?: string;
     accessToken?: string;

package/dist/lib/auth.js CHANGED Viewed

@@ -1,5 +1,6 @@
 import { getCredential } from './config.js';
-const DEFAULT_BASE_URL = 'https://api.respan.ai/api';
+export const DEFAULT_BASE_URL = 'https://api.respan.ai';
+export const ENTERPRISE_BASE_URL = 'https://endpoint.respan.ai';
 export function resolveAuth(flags) {
     if (flags['api-key']) {
         return { apiKey: flags['api-key'], baseUrl: DEFAULT_BASE_URL };

package/dist/lib/filters.d.ts ADDED Viewed

@@ -0,0 +1,24 @@
+/**
+ * Shared filter parser for CLI commands.
+ *
+ * Parses --filter strings in `field:operator:value` format into the API's
+ * `{ field: { operator, value } }` body format.
+ *
+ * Syntax:  field:operator:value
+ *   - field::value        → exact match (empty operator)
+ *   - field:gt:value      → greater than
+ *   - field:in:a,b,c      → value in list
+ *   - field:isnull:true    → null check
+ *
+ * Numeric values are auto-detected and converted.
+ * Multiple --filter flags are merged into a single filters object.
+ */
+export declare function parseFilters(filterStrings: string[]): Record<string, {
+    operator: string;
+    value: unknown[];
+}>;
+/** Filter syntax documentation for use in command descriptions */
+export declare const FILTER_SYNTAX_HELP = "FILTER SYNTAX: field:operator:value\n\nOPERATORS:\n  (empty)     Exact match         model::gpt-4\n  not         Not equal           status_code:not:200\n  gt          Greater than        cost:gt:0.01\n  gte         Greater than/equal  latency:gte:1.0\n  lt          Less than           cost:lt:0.5\n  lte         Less than/equal     prompt_tokens:lte:100\n  contains    Contains substring  error_message:contains:timeout\n  icontains   Case-insensitive    model:icontains:gpt\n  startswith  Starts with         model:startswith:gpt\n  endswith    Ends with           model:endswith:mini\n  in          Value in list       model:in:gpt-4,gpt-4o\n  isnull      Is null             error_message:isnull:true\n  iexact      Case-insens. exact  status:iexact:success";
+export declare const LOG_FIELDS_HELP = "FILTERABLE FIELDS (logs):\n  model, status_code, status, cost, latency, prompt_tokens,\n  completion_tokens, customer_identifier, custom_identifier,\n  thread_identifier, trace_unique_id, span_name, span_workflow_name,\n  environment, log_type, error_message, failed, provider_id,\n  deployment_name, prompt_name, prompt_id, unique_id, stream,\n  temperature, max_tokens, tokens_per_second, time_to_first_token,\n  total_request_tokens, metadata__<key>, scores__<evaluator_id>";
+export declare const TRACE_FIELDS_HELP = "FILTERABLE FIELDS (traces):\n  trace_unique_id, customer_identifier, environment, span_count,\n  llm_call_count, error_count, total_cost, total_tokens,\n  total_prompt_tokens, total_completion_tokens, duration,\n  span_workflow_name, metadata__<key>";
+export declare const FILTER_EXAMPLES = "EXAMPLES:\n  --filter model::gpt-4o --filter cost:gt:0.01\n  --filter status_code:not:200\n  --filter metadata__env::production\n  --filter model:in:gpt-4,gpt-4o";

package/dist/lib/filters.js ADDED Viewed

@@ -0,0 +1,100 @@
+/**
+ * Shared filter parser for CLI commands.
+ *
+ * Parses --filter strings in `field:operator:value` format into the API's
+ * `{ field: { operator, value } }` body format.
+ *
+ * Syntax:  field:operator:value
+ *   - field::value        → exact match (empty operator)
+ *   - field:gt:value      → greater than
+ *   - field:in:a,b,c      → value in list
+ *   - field:isnull:true    → null check
+ *
+ * Numeric values are auto-detected and converted.
+ * Multiple --filter flags are merged into a single filters object.
+ */
+const VALID_OPERATORS = new Set([
+    '', 'not', 'lt', 'lte', 'gt', 'gte',
+    'contains', 'icontains', 'startswith', 'endswith',
+    'in', 'isnull', 'iexact',
+]);
+function coerceValue(v) {
+    if (v === 'true')
+        return true;
+    if (v === 'false')
+        return false;
+    const n = Number(v);
+    if (!Number.isNaN(n) && v.trim() !== '')
+        return n;
+    return v;
+}
+export function parseFilters(filterStrings) {
+    const result = {};
+    for (const raw of filterStrings) {
+        // Split on first two colons: field:operator:value
+        // field::value means operator is empty string
+        const firstColon = raw.indexOf(':');
+        if (firstColon === -1) {
+            throw new Error(`Invalid filter format: "${raw}". Expected field:operator:value (e.g. model::gpt-4 or cost:gt:0.01)`);
+        }
+        const field = raw.slice(0, firstColon);
+        const rest = raw.slice(firstColon + 1);
+        const secondColon = rest.indexOf(':');
+        if (secondColon === -1) {
+            throw new Error(`Invalid filter format: "${raw}". Expected field:operator:value (e.g. model::gpt-4 or cost:gt:0.01)`);
+        }
+        const operator = rest.slice(0, secondColon);
+        const valueStr = rest.slice(secondColon + 1);
+        if (!VALID_OPERATORS.has(operator)) {
+            throw new Error(`Unknown filter operator: "${operator}". Valid operators: ${[...VALID_OPERATORS].filter(Boolean).join(', ')} (or empty for exact match)`);
+        }
+        if (!field) {
+            throw new Error(`Filter field cannot be empty: "${raw}"`);
+        }
+        // For "in" operator, split on comma to create array
+        let values;
+        if (operator === 'in') {
+            values = valueStr.split(',').map((v) => coerceValue(v.trim()));
+        }
+        else {
+            values = [coerceValue(valueStr)];
+        }
+        result[field] = { operator, value: values };
+    }
+    return result;
+}
+/** Filter syntax documentation for use in command descriptions */
+export const FILTER_SYNTAX_HELP = `FILTER SYNTAX: field:operator:value
+OPERATORS:
+  (empty)     Exact match         model::gpt-4
+  not         Not equal           status_code:not:200
+  gt          Greater than        cost:gt:0.01
+  gte         Greater than/equal  latency:gte:1.0
+  lt          Less than           cost:lt:0.5
+  lte         Less than/equal     prompt_tokens:lte:100
+  contains    Contains substring  error_message:contains:timeout
+  icontains   Case-insensitive    model:icontains:gpt
+  startswith  Starts with         model:startswith:gpt
+  endswith    Ends with           model:endswith:mini
+  in          Value in list       model:in:gpt-4,gpt-4o
+  isnull      Is null             error_message:isnull:true
+  iexact      Case-insens. exact  status:iexact:success`;
+export const LOG_FIELDS_HELP = `FILTERABLE FIELDS (logs):
+  model, status_code, status, cost, latency, prompt_tokens,
+  completion_tokens, customer_identifier, custom_identifier,
+  thread_identifier, trace_unique_id, span_name, span_workflow_name,
+  environment, log_type, error_message, failed, provider_id,
+  deployment_name, prompt_name, prompt_id, unique_id, stream,
+  temperature, max_tokens, tokens_per_second, time_to_first_token,
+  total_request_tokens, metadata__<key>, scores__<evaluator_id>`;
+export const TRACE_FIELDS_HELP = `FILTERABLE FIELDS (traces):
+  trace_unique_id, customer_identifier, environment, span_count,
+  llm_call_count, error_count, total_cost, total_tokens,
+  total_prompt_tokens, total_completion_tokens, duration,
+  span_workflow_name, metadata__<key>`;
+export const FILTER_EXAMPLES = `EXAMPLES:
+  --filter model::gpt-4o --filter cost:gt:0.01
+  --filter status_code:not:200
+  --filter metadata__env::production
+  --filter model:in:gpt-4,gpt-4o`;

package/oclif.manifest.json CHANGED Viewed

@@ -61,7 +61,7 @@
       "description": "Log in to Respan",
       "flags": {
         "api-key": {
-          "description": "API key to store",
+          "description": "API key to store (skips interactive prompt)",
           "name": "api-key",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -102,12 +102,17 @@
           "type": "option"
         },
         "base-url": {
-          "description": "API base URL",
+          "description": "API base URL (auto-detected from login method if not set)",
           "name": "base-url",
-          "default": "https://api.respan.ai/api",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
+        },
+        "enterprise": {
+          "description": "Use enterprise SSO login",
+          "name": "enterprise",
+          "allowNo": false,
+          "type": "boolean"
         }
       },
       "hasDynamicHelp": false,
@@ -1728,7 +1733,7 @@
     "logs:list": {
       "aliases": [],
       "args": {},
-      "description": "List log spans",
+      "description": "List and filter LLM request logs (spans).\n\nSupports pagination, sorting, time range, and server-side filtering.\n\nFILTER SYNTAX: field:operator:value\n\nOPERATORS:\n  (empty)     Exact match         model::gpt-4\n  not         Not equal           status_code:not:200\n  gt          Greater than        cost:gt:0.01\n  gte         Greater than/equal  latency:gte:1.0\n  lt          Less than           cost:lt:0.5\n  lte         Less than/equal     prompt_tokens:lte:100\n  contains    Contains substring  error_message:contains:timeout\n  icontains   Case-insensitive    model:icontains:gpt\n  startswith  Starts with         model:startswith:gpt\n  endswith    Ends with           model:endswith:mini\n  in          Value in list       model:in:gpt-4,gpt-4o\n  isnull      Is null             error_message:isnull:true\n  iexact      Case-insens. exact  status:iexact:success\n\nFILTERABLE FIELDS (logs):\n  model, status_code, status, cost, latency, prompt_tokens,\n  completion_tokens, customer_identifier, custom_identifier,\n  thread_identifier, trace_unique_id, span_name, span_workflow_name,\n  environment, log_type, error_message, failed, provider_id,\n  deployment_name, prompt_name, prompt_id, unique_id, stream,\n  temperature, max_tokens, tokens_per_second, time_to_first_token,\n  total_request_tokens, metadata__<key>, scores__<evaluator_id>\n\nEXAMPLES:\n  --filter model::gpt-4o --filter cost:gt:0.01\n  --filter status_code:not:200\n  --filter metadata__env::production\n  --filter model:in:gpt-4,gpt-4o",
       "flags": {
         "api-key": {
           "description": "API key (env: RESPAN_API_KEY)",
@@ -1765,7 +1770,7 @@
           "type": "boolean"
         },
         "limit": {
-          "description": "Number of results per page",
+          "description": "Number of results per page (max 1000)",
           "name": "limit",
           "default": 50,
           "hasDynamicHelp": false,
@@ -1781,7 +1786,7 @@
           "type": "option"
         },
         "sort-by": {
-          "description": "Sort field",
+          "description": "Sort field (prefix with - for descending, e.g. -cost, -latency)",
           "name": "sort-by",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -1802,11 +1807,32 @@
           "type": "option"
         },
         "filter": {
-          "description": "Filter expression",
+          "description": "Filter in field:operator:value format (repeatable)",
           "name": "filter",
           "hasDynamicHelp": false,
           "multiple": true,
           "type": "option"
+        },
+        "all-envs": {
+          "description": "Include all environments (true/false)",
+          "name": "all-envs",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "is-test": {
+          "description": "Filter by test (true) or production (false) environment",
+          "name": "is-test",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "include-fields": {
+          "description": "Comma-separated fields to include in response",
+          "name": "include-fields",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
         }
       },
       "hasDynamicHelp": false,
@@ -1828,7 +1854,7 @@
     "logs:summary": {
       "aliases": [],
       "args": {},
-      "description": "Get a summary of log spans for a time range",
+      "description": "Get aggregated summary statistics for log spans in a time range.\n\nReturns total cost, total tokens, request count, and score summaries.\n\nFILTER SYNTAX: field:operator:value\n\nOPERATORS:\n  (empty)     Exact match         model::gpt-4\n  not         Not equal           status_code:not:200\n  gt          Greater than        cost:gt:0.01\n  gte         Greater than/equal  latency:gte:1.0\n  lt          Less than           cost:lt:0.5\n  lte         Less than/equal     prompt_tokens:lte:100\n  contains    Contains substring  error_message:contains:timeout\n  icontains   Case-insensitive    model:icontains:gpt\n  startswith  Starts with         model:startswith:gpt\n  endswith    Ends with           model:endswith:mini\n  in          Value in list       model:in:gpt-4,gpt-4o\n  isnull      Is null             error_message:isnull:true\n  iexact      Case-insens. exact  status:iexact:success\n\nFILTERABLE FIELDS (logs):\n  model, status_code, status, cost, latency, prompt_tokens,\n  completion_tokens, customer_identifier, custom_identifier,\n  thread_identifier, trace_unique_id, span_name, span_workflow_name,\n  environment, log_type, error_message, failed, provider_id,\n  deployment_name, prompt_name, prompt_id, unique_id, stream,\n  temperature, max_tokens, tokens_per_second, time_to_first_token,\n  total_request_tokens, metadata__<key>, scores__<evaluator_id>\n\nEXAMPLES:\n  --filter model::gpt-4o --filter cost:gt:0.01\n  --filter status_code:not:200\n  --filter metadata__env::production\n  --filter model:in:gpt-4,gpt-4o",
       "flags": {
         "api-key": {
           "description": "API key (env: RESPAN_API_KEY)",
@@ -1879,6 +1905,27 @@
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
+        },
+        "filter": {
+          "description": "Filter in field:operator:value format (repeatable)",
+          "name": "filter",
+          "hasDynamicHelp": false,
+          "multiple": true,
+          "type": "option"
+        },
+        "all-envs": {
+          "description": "Include all environments (true/false)",
+          "name": "all-envs",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "is-test": {
+          "description": "Filter by test (true) or production (false) environment",
+          "name": "is-test",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
         }
       },
       "hasDynamicHelp": false,
@@ -2388,7 +2435,7 @@
     "traces:list": {
       "aliases": [],
       "args": {},
-      "description": "List traces",
+      "description": "List and filter traces.\n\nA trace represents a complete workflow execution containing multiple spans.\n\nFILTER SYNTAX: field:operator:value\n\nOPERATORS:\n  (empty)     Exact match         model::gpt-4\n  not         Not equal           status_code:not:200\n  gt          Greater than        cost:gt:0.01\n  gte         Greater than/equal  latency:gte:1.0\n  lt          Less than           cost:lt:0.5\n  lte         Less than/equal     prompt_tokens:lte:100\n  contains    Contains substring  error_message:contains:timeout\n  icontains   Case-insensitive    model:icontains:gpt\n  startswith  Starts with         model:startswith:gpt\n  endswith    Ends with           model:endswith:mini\n  in          Value in list       model:in:gpt-4,gpt-4o\n  isnull      Is null             error_message:isnull:true\n  iexact      Case-insens. exact  status:iexact:success\n\nFILTERABLE FIELDS (traces):\n  trace_unique_id, customer_identifier, environment, span_count,\n  llm_call_count, error_count, total_cost, total_tokens,\n  total_prompt_tokens, total_completion_tokens, duration,\n  span_workflow_name, metadata__<key>\n\nEXAMPLES:\n  --filter model::gpt-4o --filter cost:gt:0.01\n  --filter status_code:not:200\n  --filter metadata__env::production\n  --filter model:in:gpt-4,gpt-4o",
       "flags": {
         "api-key": {
           "description": "API key (env: RESPAN_API_KEY)",
@@ -2441,7 +2488,7 @@
           "type": "option"
         },
         "sort-by": {
-          "description": "Sort field",
+          "description": "Sort field (prefix with - for descending)",
           "name": "sort-by",
           "default": "-timestamp",
           "hasDynamicHelp": false,
@@ -2470,7 +2517,7 @@
           "type": "option"
         },
         "filter": {
-          "description": "Filter expression",
+          "description": "Filter in field:operator:value format (repeatable)",
           "name": "filter",
           "hasDynamicHelp": false,
           "multiple": true,
@@ -2882,5 +2929,5 @@
       ]
     }
   },
-  "version": "0.2.0"
+  "version": "0.3.1"
 }

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@respan/cli",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Respan CLI - manage your LLM observability from the command line",
   "type": "module",
   "main": "dist/index.js",