@respan/cli 0.9.0 → 0.10.0

package/dist/commands/setup/index.js

@@ -8,6 +8,7 @@ import { BaseCommand } from '../../lib/base-command.js';
 import { printBanner } from '../../lib/banner.js';
 import { findProjectRoot, writeTextFile, readTextFile, ensureDir, } from '../../lib/integrate.js';
 import { createSpinner } from '../../lib/spinner.js';
+import { TRACING_MD, GATEWAY_MD, PROMPTS_MD, EVALS_MD, MONITORS_MD, } from '#lib/skill-refs.generated.js';
 // ── Shared skill content (same for all agents) ────────────────────────
 // ── Skill files ────────────────────────────────────────────────────────
 const SKILL_MD = `# Respan
@@ -16,196 +17,43 @@ Use the Respan CLI and SDK for LLM observability — tracing, evals, prompts, da
 
 ## When To Use
 
-- The user asks to **set up Respan** or **add tracing** → read [references/setup.md](references/setup.md)
-- The user asks about **traces, logs, prompts, datasets, evals** → read [references/platform.md](references/platform.md)
-- The user asks about **gateway routing** or **proxying LLM calls** → read [references/gateway.md](references/gateway.md)
-- You need to run a Respan CLI command → check [references/platform.md](references/platform.md) for command reference
+- **Set up Respan** or **add tracing** → read [references/setup.md](references/setup.md)
+- **Advanced tracing** (decorators, propagation, processors) → read [references/tracing.md](references/tracing.md)
+- **Gateway routing** or **proxying LLM calls** → read [references/gateway.md](references/gateway.md)
+- **Prompt management** (create, version, deploy) → read [references/prompts.md](references/prompts.md)
+- **Evals** (datasets, evaluators, experiments) → read [references/evals.md](references/evals.md)
+- **Monitors & automation** (alerts, online evals, webhooks) → read [references/monitors.md](references/monitors.md)
 
 ## Core Principles
 
-1. **Documentation First**: Always fetch current docs before implementing. Respan updates frequently. See docs access methods below.
-2. **CLI for Data Access**: Use \`respan\` CLI when querying/modifying Respan data.
-3. **Check References**: Read the relevant reference file before implementing any workflow.
+1. **Read the reference first.** Each reference file has the exact API patterns, MCP tools, and CLI commands.
+2. **Use MCP tools** for platform operations (prompts, datasets, evaluators, experiments, traces, logs).
+3. **Use CLI** when MCP is not available: \`respan traces list\`, \`respan prompts list\`, etc.
+4. **Fetch docs** for integration-specific details not covered in references.
 
 ## Quick Reference
 
-| Task | Command / Action |
-|------|-----------------|
-| Set up SDK tracing | Follow [references/setup.md](references/setup.md) |
+| Task | Reference / Command |
+|------|--------------------|
+| Set up SDK tracing | [references/setup.md](references/setup.md) |
+| Decorators & propagation | [references/tracing.md](references/tracing.md) |
+| Gateway routing | [references/gateway.md](references/gateway.md) |
+| Prompt management | [references/prompts.md](references/prompts.md) |
+| Evals & experiments | [references/evals.md](references/evals.md) |
+| Monitors & automation | [references/monitors.md](references/monitors.md) |
 | List traces | \`respan traces list --limit 10\` |
 | View a trace | \`respan traces get <id>\` |
-| List prompts | \`respan prompts list\` |
-| Create dataset | \`respan datasets create --name <name>\` |
-| Run evaluator | \`respan evaluators run <id>\` |
 | Check auth | \`respan auth status\` |
-| View logs | \`respan logs list --limit 10\` |
 
 ## Documentation Access
 
-Three methods to access Respan docs, in order of preference:
-
-### 1. Documentation Index (llms.txt)
-
-Fetch the full index of all doc pages:
-\`https://www.respan.ai/docs/llms.txt\`
-
-Use this to discover the right page for a topic, then fetch that page directly.
-
-### 2. Fetch Individual Pages as Markdown
-
-Any integration or SDK doc page can be fetched by changing \`.mdx\` to \`.md\`:
+Any doc page can be fetched as markdown:
 \`https://respan.ai/docs/integrations/openai-sdk.md\`
 \`https://respan.ai/docs/sdks/typescript-sdk/overview.md\`
 
-### 3. Platform
-
-View traces, logs, and analytics at: \`https://platform.respan.ai\`
-`;
-const GATEWAY_MD = `# Respan Gateway
-
-Route LLM calls through the Respan proxy for logging, caching, key management, and model switching.
-
-## Setup
-
-Point the LLM client's base URL at the Respan gateway. The API key authenticates both the proxy and tracing.
-
-### TypeScript
-
-\`\`\`typescript
-import OpenAI from "openai";
-
-const client = new OpenAI({
-  apiKey: process.env.RESPAN_API_KEY,
-  baseURL: process.env.RESPAN_BASE_URL || "https://api.respan.ai/api",
-});
-\`\`\`
-
-### Python
-
-\`\`\`python
-import os
-from openai import OpenAI
-
-client = OpenAI(
-    api_key=os.environ["RESPAN_API_KEY"],
-    base_url=os.getenv("RESPAN_BASE_URL", "https://api.respan.ai/api"),
-)
-\`\`\`
-
-## Gateway + Tracing (Both)
-
-Combine SDK tracing and gateway routing — initialize Respan for tracing AND point the LLM client at the gateway.
-
-## Features
-
-- **Unified key management** — one API key for all providers
-- **Caching** — cache repeated LLM calls
-- **Fallbacks** — automatic failover between providers
-- **Cost tracking** — per-request cost logging
-- **Model switching** — swap models without code changes
-
-## Docs
-
-- Quickstart: \`https://respan.ai/docs/documentation/features/gateway/gateway-quickstart.md\`
-- Advanced: \`https://respan.ai/docs/documentation/features/gateway/advanced.md\`
-- Provider setup: \`https://respan.ai/docs/integrations/providers/openai.md\`
-`;
-const PLATFORM_MD = `# Respan Platform
-
-Use the Respan CLI and platform for traces, logs, prompts, datasets, evaluations, and monitoring.
-
-## CLI Commands
-
-### Auth
-\`\`\`bash
-respan auth login          # Log in (browser or API key)
-respan auth status         # Check current auth
-respan auth logout         # Log out
-respan whoami              # Show current user
-\`\`\`
-
-### Traces
-\`\`\`bash
-respan traces list --limit 10          # List recent traces
-respan traces get <trace-id>           # Get trace details
-respan traces summary                  # Trace summary stats
-\`\`\`
-
-### Logs
-\`\`\`bash
-respan logs list --limit 10            # List recent logs
-respan logs get <log-id>               # Get log details
-respan logs summary                    # Log summary stats
-respan logs create --data '{...}'      # Create a log entry
-\`\`\`
-
-### Prompts
-\`\`\`bash
-respan prompts list                    # List all prompts
-respan prompts get <id>                # Get prompt details
-respan prompts create --name <name>    # Create a prompt
-respan prompts update <id>             # Update a prompt
-respan prompts versions <id>           # List prompt versions
-\`\`\`
-
-### Datasets
-\`\`\`bash
-respan datasets list                   # List datasets
-respan datasets create --name <name>   # Create a dataset
-respan datasets get <id>               # Get dataset details
-respan datasets spans <id>             # List dataset spans
-respan datasets add-spans <id>         # Add spans to dataset
-\`\`\`
-
-### Evaluators
-\`\`\`bash
-respan evaluators list                 # List evaluators
-respan evaluators get <id>             # Get evaluator details
-respan evaluators create               # Create an evaluator
-respan evaluators run <id>             # Run an evaluator
-\`\`\`
-
-### Experiments
-\`\`\`bash
-respan experiments list                # List experiments
-respan experiments get <id>            # Get experiment details
-respan experiments create              # Create an experiment
-\`\`\`
-
-### Integration (CLI agent tracing)
-\`\`\`bash
-respan integrate claude-code           # Trace Claude Code conversations
-respan integrate codex-cli             # Trace Codex CLI conversations
-respan integrate gemini-cli            # Trace Gemini CLI conversations
-respan integrate opencode              # Trace OpenCode conversations
-respan integrate <tool> --disable      # Disable tracing
-\`\`\`
-
-### Config
-\`\`\`bash
-respan config list                     # List all config
-respan config get <key>                # Get config value
-respan config set <key> <value>        # Set config value
-\`\`\`
-
-## Platform Features
-
-- **Traces** — structured spans showing LLM call hierarchy, inputs/outputs, tokens, cost
-- **Logs** — request-level logging with metadata
-- **Prompts** — version-controlled prompt templates with deployment
-- **Datasets** — curated test data for evaluations
-- **Evaluators** — automated scoring/grading of LLM outputs
-- **Experiments** — run evals over datasets and compare results
-- **Monitors** — metric-based alerts for production regressions
-- **Views** — saved filters for quick access
-
-## Docs
+Full docs index: \`https://www.respan.ai/docs/llms.txt\`
 
-- Tracing concepts: \`https://respan.ai/docs/documentation/features/tracing/concepts.md\`
-- Evals concepts: \`https://respan.ai/docs/documentation/features/evals/concepts.md\`
-- Prompts: \`https://respan.ai/docs/documentation/features/prompt-management/prompt-management-quickstart.md\`
-- Monitoring: \`https://respan.ai/docs/documentation/features/monitoring/metrics.md\`
-- Full docs: \`https://www.respan.ai/docs/llms.txt\`
+Platform: \`https://platform.respan.ai\`
 `;
 const SETUP_MD = `# Respan Setup
 
@@ -247,9 +95,9 @@ Check higher-priority categories first. If a match is found, use that instrument
 | Pydantic AI | \`pydantic-ai\` | — | \`respan-instrumentation-pydantic-ai\` | — | [docs](https://respan.ai/docs/integrations/pydantic-ai.md) |
 | LangChain | \`langchain\` | \`langchain\` | via OpenInference | — | [docs](https://respan.ai/docs/integrations/langchain.md) |
 | LangGraph | \`langgraph\` | — | via OpenInference | — | [docs](https://respan.ai/docs/integrations/langgraph.md) |
-| CrewAI | \`crewai\` | — | via OpenInference | — | [docs](https://respan.ai/docs/integrations/crewai.md) |
+| CrewAI | \`crewai\` | — | \`respan-instrumentation-crewai\` | — | [docs](https://respan.ai/docs/integrations/crewai.md) |
 | LlamaIndex | \`llama-index\` | — | via OpenInference | — | [docs](https://respan.ai/docs/integrations/llama-index.md) |
-| Haystack | \`haystack-ai\` | — | via exporter | — | [docs](https://respan.ai/docs/integrations/haystack.md) |
+| Haystack | \`haystack-ai\` | — | \`respan-instrumentation-haystack\` | — | [docs](https://respan.ai/docs/integrations/haystack.md) |
 | Mastra | — | \`mastra\` | — | via OTEL | [docs](https://respan.ai/docs/integrations/mastra.md) |
 | Google ADK | \`google-adk\` | — | via OpenInference | — | [docs](https://respan.ai/docs/integrations/google-adk.md) |
 
@@ -619,6 +467,8 @@ class Setup extends BaseCommand {
                     attr('gen_ai.system', 'openai'),
                     attr('gen_ai.request.model', 'gpt-4o-mini'),
                     attr('gen_ai.response.model', 'gpt-4o-mini'),
+                    intAttr('gen_ai.usage.input_tokens', 145),
+                    intAttr('gen_ai.usage.output_tokens', 38),
                     intAttr('gen_ai.usage.prompt_tokens', 145),
                     intAttr('gen_ai.usage.completion_tokens', 38),
                     attr('traceloop.entity.input', '[{"role": "system", "content": "Classify the customer intent."}, {"role": "user", "content": "My order #12345 hasn\'t arrived yet"}]'),
@@ -652,6 +502,8 @@ class Setup extends BaseCommand {
                     attr('gen_ai.system', 'openai'),
                     attr('gen_ai.request.model', 'gpt-4o-mini'),
                     attr('gen_ai.response.model', 'gpt-4o-mini'),
+                    intAttr('gen_ai.usage.input_tokens', 210),
+                    intAttr('gen_ai.usage.output_tokens', 85),
                     intAttr('gen_ai.usage.prompt_tokens', 210),
                     intAttr('gen_ai.usage.completion_tokens', 85),
                     attr('traceloop.entity.input', '[{"role": "system", "content": "Generate a helpful response to the customer."}, {"role": "user", "content": "Order delayed, refund initiated for #12345"}]'),
@@ -782,8 +634,11 @@ class Setup extends BaseCommand {
             ensureDir(refsDir);
             writeTextFile(path.join(skillDir, 'SKILL.md'), this.getSkillMd());
             writeTextFile(path.join(refsDir, 'setup.md'), SETUP_MD);
-            writeTextFile(path.join(refsDir, 'platform.md'), PLATFORM_MD);
+            writeTextFile(path.join(refsDir, 'tracing.md'), TRACING_MD);
             writeTextFile(path.join(refsDir, 'gateway.md'), GATEWAY_MD);
+            writeTextFile(path.join(refsDir, 'prompts.md'), PROMPTS_MD);
+            writeTextFile(path.join(refsDir, 'evals.md'), EVALS_MD);
+            writeTextFile(path.join(refsDir, 'monitors.md'), MONITORS_MD);
         };
         // Write to ~/.agents/skills/ (Cursor, Codex, Gemini CLI, OpenCode)
         writeSkillTo(path.join(home, '.agents', 'skills'));

package/dist/commands/traces/get.js

@@ -6,7 +6,7 @@ class TracesGet extends BaseCommand {
         this.globalFlags = flags;
         try {
             const client = this.getClient();
-            const data = await this.spin('Fetching trace', () => client.traces.retrieveTrace({ trace_unique_id: args.id }));
+            const data = await this.spin('Fetching trace', () => client.traces.retrieveTrace({ Authorization: this.getAuthHeader(), trace_unique_id: args.id }));
             this.log(JSON.stringify(data, null, 2));
         }
         catch (error) {

package/dist/commands/traces/list.js

@@ -8,22 +8,20 @@ class TracesList extends BaseCommand {
         this.globalFlags = flags;
         try {
             const client = this.getClient();
-            let bodyFilters = {};
+            let bodyFilters;
             if (flags.filter && flags.filter.length > 0) {
                 bodyFilters = parseFilters(flags.filter);
             }
-            const queryParams = {
+            const data = await this.spin('Fetching traces', () => client.traces.listTraces({
+                Authorization: this.getAuthHeader(),
                 page_size: flags.limit,
                 page: flags.page,
                 sort_by: flags['sort-by'],
-            };
-            if (flags['start-time'])
-                queryParams.start_time = flags['start-time'];
-            if (flags['end-time'])
-                queryParams.end_time = flags['end-time'];
-            if (flags.environment)
-                queryParams.environment = flags.environment;
-            const data = await this.spin('Fetching traces', () => client.traces.list({ filters: bodyFilters }, { queryParams }));
+                ...(flags['start-time'] ? { start_time: flags['start-time'] } : {}),
+                ...(flags['end-time'] ? { end_time: flags['end-time'] } : {}),
+                ...(flags.environment ? { environment: flags.environment } : {}),
+                ...(bodyFilters ? { filters: bodyFilters } : {}),
+            }));
             this.outputResult(data, [
                 'trace_unique_id', 'name', 'duration', 'span_count', 'total_cost', 'error_count', 'start_time',
             ]);

package/dist/commands/traces/summary.js

@@ -6,7 +6,11 @@ class TracesSummary extends BaseCommand {
         this.globalFlags = flags;
         try {
             const client = this.getClient();
-            const data = await this.spin('Fetching traces summary', () => client.traces.retrieveTracesSummary({ start_time: flags['start-time'], end_time: flags['end-time'] }));
+            const data = await this.spin('Fetching traces summary', () => client.spans.getSpansSummary({
+                Authorization: this.getAuthHeader(),
+                start_time: flags['start-time'],
+                end_time: flags['end-time'],
+            }));
             this.log(JSON.stringify(data, null, 2));
         }
         catch (error) {
@@ -14,7 +18,7 @@ class TracesSummary extends BaseCommand {
         }
     }
 }
-TracesSummary.description = 'Get a summary of traces for a time range';
+TracesSummary.description = 'Get a span-level summary of activity for a time range (counts, latency, cost, errors aggregated across spans)';
 TracesSummary.flags = {
     ...BaseCommand.baseFlags,
     'start-time': Flags.string({ description: 'Start time (ISO 8601)', required: true }),

package/dist/commands/users/get.js

@@ -6,7 +6,7 @@ class UsersGet extends BaseCommand {
         this.globalFlags = flags;
         try {
             const client = this.getClient();
-            const data = await this.spin('Fetching user', () => client.users.retrieveUser({ customer_identifier: args.id }));
+            const data = await this.spin('Fetching user', () => client.users.retrieveUser({ Authorization: this.getAuthHeader(), customer_identifier: args.id }));
             this.log(JSON.stringify(data, null, 2));
         }
         catch (error) {

package/dist/commands/users/list.js

@@ -7,15 +7,13 @@ class UsersList extends BaseCommand {
         this.globalFlags = flags;
         try {
             const client = this.getClient();
-            const params = {
+            const data = await this.spin('Fetching users', () => client.users.listCustomers({
+                Authorization: this.getAuthHeader(),
                 page_size: flags.limit,
                 page: flags.page,
-            };
-            if (flags['sort-by'])
-                params.sort_by = flags['sort-by'];
-            if (flags.environment)
-                params.environment = flags.environment;
-            const data = await this.spin('Fetching users', () => client.users.list(params));
+                ...(flags['sort-by'] ? { sort_by: flags['sort-by'] } : {}),
+                ...(flags.environment ? { environment: flags.environment } : {}),
+            }));
             this.outputResult(data, [
                 'customer_identifier', 'name', 'email', 'number_of_requests', 'total_cost', 'last_active_timeframe',
             ]);

package/dist/lib/base-command.d.ts

@@ -14,6 +14,8 @@ export declare abstract class BaseCommand extends Command {
     protected globalFlags: GlobalFlags;
     protected getAuth(): AuthConfig;
     protected getClient(): RespanClient;
+    protected getAuthHeader(): string;
+    protected getBaseUrl(): string;
     protected getOutputFormat(): 'json' | 'csv' | 'table';
     protected outputResult(data: unknown, columns?: string[]): void;
     protected spin<T>(label: string, fn: () => Promise<T>): Promise<T>;

package/dist/lib/base-command.js

@@ -17,10 +17,20 @@ export class BaseCommand extends Command {
         if (!token)
             throw new Error('No API key or access token available.');
         return new RespanClient({
-            token,
+            headers: { Authorization: `Bearer ${token}` },
             ...(auth.baseUrl ? { environment: auth.baseUrl } : {}),
         });
     }
+    getAuthHeader() {
+        const auth = this.getAuth();
+        const token = auth.apiKey || auth.accessToken;
+        if (!token)
+            throw new Error('No API key or access token available.');
+        return `Bearer ${token}`;
+    }
+    getBaseUrl() {
+        return this.getAuth().baseUrl || 'https://api.respan.ai';
+    }
     getOutputFormat() {
         if (this.globalFlags.json)
             return 'json';

package/dist/lib/eval/runner.d.ts

@@ -0,0 +1,15 @@
+import { RespanClient } from '@respan/respan-api';
+export interface RunEvalResult {
+    prompt_id: string;
+    prompt_version_id?: string;
+    prompt_version_deployed?: number;
+    dataset_id: string;
+    evaluator_workflow_ids: string[];
+    experiment_id: string;
+    created_prompt: boolean;
+    created_dataset: boolean;
+    created_experiment: boolean;
+    evaluators_created: number;
+    rows_added: number;
+}
+export declare function runEval(filePath: string, client: RespanClient, authHeader: string, baseUrl: string, log?: (msg: string) => void): Promise<RunEvalResult>;