@respan/cli 0.4.1 → 0.5.0

package/dist/assets/assets/hook.py

@@ -81,6 +81,38 @@ def save_state(state: Dict[str, Any]) -> None:
         STATE_FILE.write_text(json.dumps(state, indent=2), encoding="utf-8")
 
 
+# Known config keys in respan.json that map to span fields.
+# Anything else is treated as a custom property (goes into metadata).
+KNOWN_CONFIG_KEYS = {"customer_id", "span_name", "workflow_name"}
+
+
+def load_respan_config(cwd: str) -> Dict[str, Any]:
+    """Load .claude/respan.json from the project directory.
+
+    Returns a dict with two keys:
+      - "fields": known span fields (customer_id, span_name, workflow_name)
+      - "properties": everything else (custom properties → metadata)
+    """
+    config_path = Path(cwd) / ".claude" / "respan.json"
+    if not config_path.exists():
+        return {"fields": {}, "properties": {}}
+    try:
+        raw = json.loads(config_path.read_text(encoding="utf-8"))
+        if not isinstance(raw, dict):
+            return {"fields": {}, "properties": {}}
+        fields = {}
+        properties = {}
+        for k, v in raw.items():
+            if k in KNOWN_CONFIG_KEYS:
+                fields[k] = v
+            else:
+                properties[k] = v
+        return {"fields": fields, "properties": properties}
+    except (json.JSONDecodeError, IOError) as e:
+        debug(f"Failed to load respan.json from {config_path}: {e}")
+        return {"fields": {}, "properties": {}}
+
+
 def get_content(msg: Dict[str, Any]) -> Any:
     """Extract content from a message."""
     if isinstance(msg, dict):
@@ -317,6 +349,7 @@ def create_respan_spans(
     user_msg: Dict[str, Any],
     assistant_msgs: List[Dict[str, Any]],
     tool_results: List[Dict[str, Any]],
+    config: Optional[Dict[str, Any]] = None,
 ) -> List[Dict[str, Any]]:
     """Create Respan span logs for a single turn with all available metadata.
 
@@ -395,16 +428,20 @@ def create_respan_spans(
     if final_output:
         completion_message = {"role": "assistant", "content": final_output}
 
-    # IDs
+    # IDs — respan.json fields, then env var overrides
+    cfg_fields = (config or {}).get("fields", {})
+    cfg_props = (config or {}).get("properties", {})
+
     trace_unique_id = f"{session_id}_turn_{turn_num}"
-    workflow_name = "claude-code"
-    user_preview = (user_text[:60] + "...") if user_text and len(user_text) > 60 else (user_text or f"turn_{turn_num}")
-    root_span_name = f"Turn {turn_num}: {user_preview}"
+    workflow_name = os.environ.get("RESPAN_WORKFLOW_NAME") or cfg_fields.get("workflow_name") or "claude-code"
+    root_span_name = os.environ.get("RESPAN_SPAN_NAME") or cfg_fields.get("span_name") or "claude-code"
     thread_id = f"claudecode_{session_id}"
-    customer_id = os.environ.get("RESPAN_CUSTOMER_ID", "claude-code")
+    customer_id = os.environ.get("RESPAN_CUSTOMER_ID") or cfg_fields.get("customer_id") or ""
 
-    # Metadata
+    # Metadata — custom properties from respan.json, then env overrides
     metadata: Dict[str, Any] = {"claude_code_turn": turn_num}
+    if cfg_props:
+        metadata.update(cfg_props)
     if request_id:
         metadata["request_id"] = request_id
     if stop_reason:
@@ -454,8 +491,8 @@ def create_respan_spans(
         "span_unique_id": root_span_id,
         "span_name": root_span_name,
         "span_workflow_name": workflow_name,
+        "model": model,
         "span_path": "",
-        "log_type": "agent",
         "input": json.dumps(prompt_messages) if prompt_messages else "",
         "output": json.dumps(completion_message) if completion_message else "",
         "timestamp": timestamp_str,
@@ -485,7 +522,6 @@ def create_respan_spans(
         "span_name": "claude.chat",
         "span_workflow_name": workflow_name,
         "span_path": "claude_chat",
-        "log_type": "generation",
         "model": model,
         "provider_id": "anthropic",
         "input": json.dumps(prompt_messages) if prompt_messages else "",
@@ -524,7 +560,6 @@ def create_respan_spans(
                     "span_name": f"Thinking {thinking_num}",
                     "span_workflow_name": workflow_name,
                     "span_path": "thinking",
-                    "log_type": "generation",
                     "input": "",
                     "output": thinking_text,
                     "timestamp": thinking_ts,
@@ -575,7 +610,6 @@ def create_respan_spans(
             "span_name": f"Tool: {td['name']}",
             "span_workflow_name": workflow_name,
             "span_path": f"tool_{td['name'].lower()}",
-            "log_type": "tool",
             "input": format_tool_input(td["name"], td["input"]),
             "output": format_tool_output(td["name"], td.get("output")),
             "timestamp": tool_ts,
@@ -588,6 +622,26 @@ def create_respan_spans(
                 tool_span["latency"] = duration_ms / 1000.0
         spans.append(tool_span)
 
+    # Add required Respan platform fields to every span.
+    # The backend expects these on all spans (per official SDK examples).
+    respan_defaults = {
+        "warnings": "",
+        "encoding_format": "float",
+        "disable_fallback": False,
+        "respan_params": {
+            "has_webhook": False,
+            "environment": os.environ.get("RESPAN_ENVIRONMENT", "prod"),
+        },
+        "field_name": "data: ",
+        "delimiter": "\n\n",
+        "disable_log": False,
+        "request_breakdown": False,
+    }
+    for span in spans:
+        for key, value in respan_defaults.items():
+            if key not in span:
+                span[key] = value
+
     return spans
 
 
@@ -597,36 +651,49 @@ def send_spans(
     base_url: str,
     turn_num: int,
 ) -> None:
-    """Send spans to Respan with timeout and one retry on transient errors."""
+    """Send spans to Respan as a single batch (matches official SDK behaviour).
+
+    The official Respan tracing SDK sends all spans for a trace in one
+    POST request to ``/v1/traces/ingest``.  We do the same here, with
+    simple retry logic for transient server errors.
+    """
     url = f"{base_url}/v1/traces/ingest"
     headers = {"Authorization": f"Bearer {api_key}"}
 
-    for attempt in range(2):
+    span_names = [s.get("span_name", "?") for s in spans]
+    payload_json = json.dumps(spans)
+    payload_size = len(payload_json)
+    debug(f"Sending {len(spans)} spans ({payload_size} bytes) for turn {turn_num}: {span_names}")
+    if DEBUG:
+        debug_file = LOG_FILE.parent / f"respan_spans_turn_{turn_num}.json"
+        debug_file.write_text(payload_json, encoding="utf-8")
+        debug(f"Dumped spans to {debug_file}")
+
+    for attempt in range(3):
         try:
             response = requests.post(url, json=spans, headers=headers, timeout=30)
             if response.status_code < 400:
-                debug(f"Sent {len(spans)} spans for turn {turn_num}")
+                resp_text = response.text[:300] if response.text else ""
+                debug(f"Sent {len(spans)} spans for turn {turn_num} "
+                      f"(attempt {attempt + 1}): {resp_text}")
                 return
             if response.status_code < 500:
-                # 4xx — not retryable
-                log("ERROR", f"Failed to send spans for turn {turn_num}: HTTP {response.status_code}")
+                log("ERROR", f"Spans rejected for turn {turn_num}: "
+                    f"HTTP {response.status_code} - {response.text[:200]}")
                 return
-            # 5xx — retryable
-            if attempt == 0:
-                debug(f"Server error {response.status_code} for turn {turn_num}, retrying...")
-                time.sleep(1)
-                continue
-            log("ERROR", f"Failed to send spans for turn {turn_num} after retry: HTTP {response.status_code}")
-        except (requests.exceptions.Timeout, requests.exceptions.ConnectionError) as e:
-            if attempt == 0:
-                debug(f"Transient error for turn {turn_num}: {e}, retrying...")
-                time.sleep(1)
-                continue
-            log("ERROR", f"Failed to send spans for turn {turn_num} after retry: {e}")
+            # 5xx — retry after short delay
+            debug(f"Server error for turn {turn_num} "
+                  f"(attempt {attempt + 1}), retrying...")
+            time.sleep(1.0)
+        except (requests.exceptions.Timeout, requests.exceptions.ConnectionError):
+            time.sleep(1.0)
         except Exception as e:
             log("ERROR", f"Failed to send spans for turn {turn_num}: {e}")
             return
 
+    log("ERROR", f"Failed to send {len(spans)} spans for turn {turn_num} "
+        f"after 3 attempts")
+
 
 def process_transcript(
     session_id: str,
@@ -634,6 +701,7 @@ def process_transcript(
     state: Dict[str, Any],
     api_key: str,
     base_url: str,
+    config: Optional[Dict[str, Any]] = None,
 ) -> int:
     """Process a transcript file and create traces for new turns."""
     # Get previous state for this session
@@ -683,7 +751,8 @@ def process_transcript(
         turns_processed += 1
         turn_num = turn_count + turns_processed
         spans = create_respan_spans(
-            session_id, turn_num, current_user, current_assistants, current_tool_results
+            session_id, turn_num, current_user, current_assistants, current_tool_results,
+            config=config,
         )
         send_spans(spans, api_key, base_url, turn_num)
         last_committed_line = total_lines  # safe default, refined below
@@ -745,8 +814,17 @@ def process_transcript(
         current_assistants.append(merged)
 
     if current_user and current_assistants:
-        _commit_turn()
-        last_committed_line = total_lines
+        # Check if the turn has actual text output.  The Stop hook can fire
+        # before the final assistant text block is flushed to disk, leaving
+        # only thinking/tool_use blocks.  If no text content is found, treat
+        # the turn as incomplete so the retry logic re-reads it.
+        has_text = any(get_text_content(m) for m in current_assistants)
+        if has_text:
+            _commit_turn()
+            last_committed_line = total_lines
+        else:
+            last_committed_line = current_user_line
+            debug(f"Turn has assistant msgs but no text output yet (likely not flushed), will retry")
     else:
         # Incomplete turn — rewind so the next run re-reads from the
         # unmatched user message (or from where we left off if no user).
@@ -859,13 +937,32 @@ def main():
         debug("Tracing disabled (TRACE_TO_RESPAN != true)")
         sys.exit(0)
 
-    # Check for required environment variables
+    # Resolve API key: env var > ~/.config/respan/credentials.json
     api_key = os.getenv("RESPAN_API_KEY")
-    # Default: api.respan.ai | Enterprise: endpoint.respan.ai (set RESPAN_BASE_URL)
     base_url = os.getenv("RESPAN_BASE_URL", "https://api.respan.ai/api")
 
     if not api_key:
-        log("ERROR", "Respan API key not set (RESPAN_API_KEY)")
+        creds_file = Path.home() / ".config" / "respan" / "credentials.json"
+        if creds_file.exists():
+            try:
+                creds = json.loads(creds_file.read_text(encoding="utf-8"))
+                # Find the active profile's credential
+                config_file = Path.home() / ".config" / "respan" / "config.json"
+                profile = "default"
+                if config_file.exists():
+                    cfg = json.loads(config_file.read_text(encoding="utf-8"))
+                    profile = cfg.get("activeProfile", "default")
+                cred = creds.get(profile, {})
+                api_key = cred.get("apiKey") or cred.get("accessToken")
+                if not base_url or base_url == "https://api.respan.ai/api":
+                    base_url = cred.get("baseUrl", base_url)
+                if api_key:
+                    debug(f"Using API key from credentials.json (profile: {profile})")
+            except (json.JSONDecodeError, IOError) as e:
+                debug(f"Failed to read credentials.json: {e}")
+
+    if not api_key:
+        log("ERROR", "No API key found. Run: respan auth login")
         sys.exit(0)
 
     # Try stdin payload first, fall back to filesystem scan
@@ -884,11 +981,49 @@ def main():
 
     debug(f"Processing session: {session_id}")
 
-    # Process the transcript under file lock
+    # Load respan.json config from the project directory.
+    # Extract the project CWD from the first user message in the transcript.
+    config: Dict[str, Any] = {"fields": {}, "properties": {}}
+    try:
+        first_line = transcript_file.read_text(encoding="utf-8").split("\n")[0]
+        if first_line:
+            first_msg = json.loads(first_line)
+            cwd = first_msg.get("cwd")
+            if not cwd:
+                # Try second line (first is often file-history-snapshot)
+                lines = transcript_file.read_text(encoding="utf-8").split("\n")
+                for line in lines[:5]:
+                    if line.strip():
+                        msg = json.loads(line)
+                        cwd = msg.get("cwd")
+                        if cwd:
+                            break
+            if cwd:
+                config = load_respan_config(cwd)
+                debug(f"Loaded respan.json config from {cwd}: {config}")
+    except Exception as e:
+        debug(f"Failed to extract CWD or load config: {e}")
+
+    # Process the transcript under file lock.
+    # Retry up to 3 times with a short delay — the Stop hook can fire
+    # before Claude Code finishes flushing the assistant response to
+    # the transcript file, causing an incomplete turn on the first read.
+    max_attempts = 3
+    turns = 0
     try:
-        with state_lock():
-            state = load_state()
-            turns = process_transcript(session_id, transcript_file, state, api_key, base_url)
+        for attempt in range(max_attempts):
+            with state_lock():
+                state = load_state()
+                turns = process_transcript(session_id, transcript_file, state, api_key, base_url, config=config)
+
+            if turns > 0:
+                break
+
+            if attempt < max_attempts - 1:
+                delay = 0.5 * (attempt + 1)
+                debug(f"No turns processed (attempt {attempt + 1}/{max_attempts}), "
+                      f"retrying in {delay}s...")
+                time.sleep(delay)
 
         # Log execution time
         duration = (datetime.now() - script_start).total_seconds()

package/dist/commands/integrate/claude-code.d.ts

@@ -8,6 +8,9 @@ export default class IntegrateClaudeCode extends BaseCommand {
         'project-id': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'base-url': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         attrs: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        'customer-id': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'span-name': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'workflow-name': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         '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>;

package/dist/commands/integrate/claude-code.js

@@ -1,15 +1,19 @@
 import * as fs from 'node:fs';
 import { execSync } from 'node:child_process';
 import { BaseCommand } from '../../lib/base-command.js';
-import { integrateFlags, deepMerge, readJsonFile, writeJsonFile, writeTextFile, expandHome, parseAttrs, getHookScript, resolveScope, findProjectRoot, DEFAULT_BASE_URL, } from '../../lib/integrate.js';
+import { integrateFlags, deepMerge, readJsonFile, writeJsonFile, writeTextFile, expandHome, parseAttrs, getHookScript, resolveScope, findProjectRoot, } from '../../lib/integrate.js';
 class IntegrateClaudeCode extends BaseCommand {
     async run() {
         const { flags } = await this.parse(IntegrateClaudeCode);
         this.globalFlags = flags;
         try {
-            const apiKey = this.resolveApiKey();
+            // Verify the user is authenticated (key is read by hook from ~/.config/respan/)
+            this.resolveApiKey();
             const baseUrl = flags['base-url'];
             const projectId = flags['project-id'];
+            const customerId = flags['customer-id'];
+            const spanName = flags['span-name'];
+            const workflowName = flags['workflow-name'];
             const attrs = parseAttrs(flags.attrs);
             const dryRun = flags['dry-run'];
             // Claude Code default: both global + local
@@ -89,20 +93,10 @@ class IntegrateClaudeCode extends BaseCommand {
                 const projectRoot = findProjectRoot();
                 const localSettingsPath = `${projectRoot}/.claude/settings.local.json`;
                 const localSettings = readJsonFile(localSettingsPath);
+                // settings.local.json: enable flag only (API key from ~/.config/respan/)
                 const envBlock = {
                     TRACE_TO_RESPAN: 'true',
-                    RESPAN_API_KEY: apiKey,
                 };
-                if (baseUrl !== DEFAULT_BASE_URL) {
-                    envBlock.RESPAN_BASE_URL = baseUrl;
-                }
-                const metadata = { ...attrs };
-                if (projectId) {
-                    metadata.project_id = projectId;
-                }
-                if (Object.keys(metadata).length > 0) {
-                    envBlock.RESPAN_METADATA = JSON.stringify(metadata);
-                }
                 const mergedLocal = deepMerge(localSettings, { env: envBlock });
                 if (dryRun) {
                     this.log(`[dry-run] Would update: ${localSettingsPath}`);
@@ -112,6 +106,36 @@ class IntegrateClaudeCode extends BaseCommand {
                     writeJsonFile(localSettingsPath, mergedLocal);
                     this.log(`Updated project settings: ${localSettingsPath}`);
                 }
+                // respan.json: non-secret config (known fields + custom properties)
+                const respanConfigPath = `${projectRoot}/.claude/respan.json`;
+                const respanConfig = readJsonFile(respanConfigPath);
+                const newConfig = { ...respanConfig };
+                if (customerId) {
+                    newConfig.customer_id = customerId;
+                }
+                if (spanName) {
+                    newConfig.span_name = spanName;
+                }
+                if (workflowName) {
+                    newConfig.workflow_name = workflowName;
+                }
+                if (projectId) {
+                    newConfig.project_id = projectId;
+                }
+                // Custom attrs go as top-level keys (unknown keys = custom properties)
+                for (const [k, v] of Object.entries(attrs)) {
+                    newConfig[k] = v;
+                }
+                if (Object.keys(newConfig).length > 0) {
+                    if (dryRun) {
+                        this.log(`[dry-run] Would write: ${respanConfigPath}`);
+                        this.log(JSON.stringify(newConfig, null, 2));
+                    }
+                    else {
+                        writeJsonFile(respanConfigPath, newConfig);
+                        this.log(`Wrote Respan config: ${respanConfigPath}`);
+                    }
+                }
             }
             // ── Done ──────────────────────────────────────────────────────
             this.log('');
@@ -126,7 +150,15 @@ class IntegrateClaudeCode extends BaseCommand {
                 this.log('Claude Code tracing enabled for this project.');
             }
             this.log('');
-            this.log('Set dynamic metadata before a session:');
+            this.log('Auth:   ~/.config/respan/credentials.json  (from `respan auth login`)');
+            this.log('Config: .claude/respan.json                (shareable, non-secret)');
+            this.log('');
+            this.log('Set properties via integrate flags or edit .claude/respan.json:');
+            this.log('  respan integrate claude-code --customer-id "frank" --span-name "my-app"');
+            this.log('  respan integrate claude-code --attrs \'{"team":"platform","env":"staging"}\'');
+            this.log('');
+            this.log('Override per-session with env vars:');
+            this.log('  export RESPAN_CUSTOMER_ID="your-name"');
             this.log("  export RESPAN_METADATA='{\"task_id\":\"T-123\"}'");
         }
         catch (error) {

package/dist/commands/integrate/codex-cli.d.ts

@@ -8,6 +8,9 @@ export default class IntegrateCodexCli extends BaseCommand {
         'project-id': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'base-url': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         attrs: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        'customer-id': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'span-name': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'workflow-name': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         '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>;

package/dist/commands/integrate/gemini-cli.d.ts

@@ -8,6 +8,9 @@ export default class IntegrateGeminiCli extends BaseCommand {
         'project-id': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'base-url': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         attrs: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        'customer-id': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'span-name': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'workflow-name': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         '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>;

package/dist/commands/integrate/opencode.d.ts

@@ -8,6 +8,9 @@ export default class IntegrateOpencode extends BaseCommand {
         'project-id': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'base-url': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         attrs: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        'customer-id': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'span-name': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'workflow-name': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         '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>;

package/dist/lib/integrate.d.ts

@@ -6,6 +6,9 @@ export declare const integrateFlags: {
     'project-id': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     'base-url': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
     attrs: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+    'customer-id': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    'span-name': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    'workflow-name': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;
 };
 export type Scope = 'local' | 'global' | 'both';

package/dist/lib/integrate.js

@@ -31,6 +31,16 @@ export const integrateFlags = {
         description: "Custom attributes JSON (e.g. '{\"env\":\"prod\"}')",
         default: '{}',
     }),
+    'customer-id': Flags.string({
+        description: 'Customer/user identifier for traces (e.g. your name or email)',
+        env: 'RESPAN_CUSTOMER_ID',
+    }),
+    'span-name': Flags.string({
+        description: 'Root span name for traces (default: claude-code)',
+    }),
+    'workflow-name': Flags.string({
+        description: 'Workflow name for traces (default: claude-code)',
+    }),
     'dry-run': Flags.boolean({
         description: 'Preview changes without writing files',
         default: false,

package/oclif.manifest.json

@@ -428,16 +428,10 @@
         "set.js"
       ]
     },
-    "datasets:add-spans": {
+    "evaluators:create": {
       "aliases": [],
-      "args": {
-        "dataset-id": {
-          "description": "Dataset ID",
-          "name": "dataset-id",
-          "required": true
-        }
-      },
-      "description": "Add existing spans to a dataset",
+      "args": {},
+      "description": "Create a new evaluator",
       "flags": {
         "api-key": {
           "description": "API key (env: RESPAN_API_KEY)",
@@ -473,18 +467,39 @@
           "allowNo": false,
           "type": "boolean"
         },
-        "span-ids": {
-          "description": "Comma-separated span IDs",
-          "name": "span-ids",
+        "name": {
+          "description": "Evaluator name",
+          "name": "name",
           "required": true,
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
+        },
+        "type": {
+          "description": "Evaluator type",
+          "name": "type",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "description": {
+          "description": "Evaluator description",
+          "name": "description",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "config": {
+          "description": "Evaluator config as JSON string",
+          "name": "config",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "datasets:add-spans",
+      "id": "evaluators:create",
       "pluginAlias": "@respan/cli",
       "pluginName": "@respan/cli",
       "pluginType": "core",
@@ -494,20 +509,20 @@
       "relativePath": [
         "dist",
         "commands",
-        "datasets",
-        "add-spans.js"
+        "evaluators",
+        "create.js"
       ]
     },
-    "datasets:create-span": {
+    "evaluators:get": {
       "aliases": [],
       "args": {
-        "dataset-id": {
-          "description": "Dataset ID",
-          "name": "dataset-id",
+        "id": {
+          "description": "Evaluator ID",
+          "name": "id",
           "required": true
         }
       },
-      "description": "Create a span in a dataset",
+      "description": "Get a specific evaluator",
       "flags": {
         "api-key": {
           "description": "API key (env: RESPAN_API_KEY)",
@@ -542,19 +557,11 @@
           "name": "verbose",
           "allowNo": false,
           "type": "boolean"
-        },
-        "body": {
-          "description": "Span body as JSON string",
-          "name": "body",
-          "required": true,
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "datasets:create-span",
+      "id": "evaluators:get",
       "pluginAlias": "@respan/cli",
       "pluginName": "@respan/cli",
       "pluginType": "core",
@@ -564,14 +571,14 @@
       "relativePath": [
         "dist",
         "commands",
-        "datasets",
-        "create-span.js"
+        "evaluators",
+        "get.js"
       ]
     },
-    "datasets:create": {
+    "evaluators:list": {
       "aliases": [],
       "args": {},
-      "description": "Create a new dataset",
+      "description": "List evaluators",
       "flags": {
         "api-key": {
           "description": "API key (env: RESPAN_API_KEY)",
@@ -607,17 +614,18 @@
           "allowNo": false,
           "type": "boolean"
         },
-        "name": {
-          "description": "Dataset name",
-          "name": "name",
-          "required": true,
+        "limit": {
+          "description": "Number of results per page",
+          "name": "limit",
+          "default": 20,
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
-        "description": {
-          "description": "Dataset description",
-          "name": "description",
+        "page": {
+          "description": "Page number",
+          "name": "page",
+          "default": 1,
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
@@ -625,7 +633,7 @@
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "datasets:create",
+      "id": "evaluators:list",
       "pluginAlias": "@respan/cli",
       "pluginName": "@respan/cli",
       "pluginType": "core",
@@ -635,25 +643,20 @@
       "relativePath": [
         "dist",
         "commands",
-        "datasets",
-        "create.js"
+        "evaluators",
+        "list.js"
       ]
     },
-    "datasets:get-span": {
+    "evaluators:run": {
       "aliases": [],
       "args": {
-        "dataset-id": {
-          "description": "Dataset ID",
-          "name": "dataset-id",
-          "required": true
-        },
-        "span-id": {
-          "description": "Span ID",
-          "name": "span-id",
+        "id": {
+          "description": "Evaluator ID",
+          "name": "id",
           "required": true
         }
       },
-      "description": "Get a specific span from a dataset",
+      "description": "Run an evaluator",
       "flags": {
         "api-key": {
           "description": "API key (env: RESPAN_API_KEY)",
@@ -688,11 +691,32 @@
           "name": "verbose",
           "allowNo": false,
           "type": "boolean"
+        },
+        "dataset-id": {
+          "description": "Dataset ID to evaluate against",
+          "name": "dataset-id",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "log-ids": {
+          "description": "Comma-separated log/span IDs to evaluate",
+          "name": "log-ids",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "params": {
+          "description": "Additional parameters as JSON string",
+          "name": "params",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "datasets:get-span",
+      "id": "evaluators:run",
       "pluginAlias": "@respan/cli",
       "pluginName": "@respan/cli",
       "pluginType": "core",
@@ -702,20 +726,20 @@
       "relativePath": [
         "dist",
         "commands",
-        "datasets",
-        "get-span.js"
+        "evaluators",
+        "run.js"
       ]
     },
-    "datasets:get": {
+    "evaluators:update": {
       "aliases": [],
       "args": {
         "id": {
-          "description": "Dataset ID",
+          "description": "Evaluator ID",
           "name": "id",
           "required": true
         }
       },
-      "description": "Get a specific dataset",
+      "description": "Update an evaluator",
       "flags": {
         "api-key": {
           "description": "API key (env: RESPAN_API_KEY)",
@@ -750,11 +774,32 @@
           "name": "verbose",
           "allowNo": false,
           "type": "boolean"
+        },
+        "name": {
+          "description": "Evaluator name",
+          "name": "name",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "description": {
+          "description": "Evaluator description",
+          "name": "description",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "config": {
+          "description": "Evaluator config as JSON string",
+          "name": "config",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "datasets:get",
+      "id": "evaluators:update",
       "pluginAlias": "@respan/cli",
       "pluginName": "@respan/cli",
       "pluginType": "core",
@@ -764,14 +809,20 @@
       "relativePath": [
         "dist",
         "commands",
-        "datasets",
-        "get.js"
+        "evaluators",
+        "update.js"
       ]
     },
-    "datasets:list": {
+    "datasets:add-spans": {
       "aliases": [],
-      "args": {},
-      "description": "List datasets",
+      "args": {
+        "dataset-id": {
+          "description": "Dataset ID",
+          "name": "dataset-id",
+          "required": true
+        }
+      },
+      "description": "Add existing spans to a dataset",
       "flags": {
         "api-key": {
           "description": "API key (env: RESPAN_API_KEY)",
@@ -807,18 +858,10 @@
           "allowNo": false,
           "type": "boolean"
         },
-        "limit": {
-          "description": "Number of results per page",
-          "name": "limit",
-          "default": 50,
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "page": {
-          "description": "Page number",
-          "name": "page",
-          "default": 1,
+        "span-ids": {
+          "description": "Comma-separated span IDs",
+          "name": "span-ids",
+          "required": true,
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
@@ -826,7 +869,7 @@
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "datasets:list",
+      "id": "datasets:add-spans",
       "pluginAlias": "@respan/cli",
       "pluginName": "@respan/cli",
       "pluginType": "core",
@@ -837,10 +880,10 @@
         "dist",
         "commands",
         "datasets",
-        "list.js"
+        "add-spans.js"
       ]
     },
-    "datasets:spans": {
+    "datasets:create-span": {
       "aliases": [],
       "args": {
         "dataset-id": {
@@ -849,7 +892,7 @@
           "required": true
         }
       },
-      "description": "List spans in a dataset",
+      "description": "Create a span in a dataset",
       "flags": {
         "api-key": {
           "description": "API key (env: RESPAN_API_KEY)",
@@ -884,11 +927,19 @@
           "name": "verbose",
           "allowNo": false,
           "type": "boolean"
+        },
+        "body": {
+          "description": "Span body as JSON string",
+          "name": "body",
+          "required": true,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "datasets:spans",
+      "id": "datasets:create-span",
       "pluginAlias": "@respan/cli",
       "pluginName": "@respan/cli",
       "pluginType": "core",
@@ -899,19 +950,13 @@
         "dist",
         "commands",
         "datasets",
-        "spans.js"
+        "create-span.js"
       ]
     },
-    "datasets:update": {
+    "datasets:create": {
       "aliases": [],
-      "args": {
-        "id": {
-          "description": "Dataset ID",
-          "name": "id",
-          "required": true
-        }
-      },
-      "description": "Update a dataset",
+      "args": {},
+      "description": "Create a new dataset",
       "flags": {
         "api-key": {
           "description": "API key (env: RESPAN_API_KEY)",
@@ -950,6 +995,7 @@
         "name": {
           "description": "Dataset name",
           "name": "name",
+          "required": true,
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
@@ -964,7 +1010,7 @@
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "datasets:update",
+      "id": "datasets:create",
       "pluginAlias": "@respan/cli",
       "pluginName": "@respan/cli",
       "pluginType": "core",
@@ -975,13 +1021,24 @@
         "dist",
         "commands",
         "datasets",
-        "update.js"
+        "create.js"
       ]
     },
-    "evaluators:create": {
+    "datasets:get-span": {
       "aliases": [],
-      "args": {},
-      "description": "Create a new evaluator",
+      "args": {
+        "dataset-id": {
+          "description": "Dataset ID",
+          "name": "dataset-id",
+          "required": true
+        },
+        "span-id": {
+          "description": "Span ID",
+          "name": "span-id",
+          "required": true
+        }
+      },
+      "description": "Get a specific span from a dataset",
       "flags": {
         "api-key": {
           "description": "API key (env: RESPAN_API_KEY)",
@@ -1016,40 +1073,11 @@
           "name": "verbose",
           "allowNo": false,
           "type": "boolean"
-        },
-        "name": {
-          "description": "Evaluator name",
-          "name": "name",
-          "required": true,
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "type": {
-          "description": "Evaluator type",
-          "name": "type",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "description": {
-          "description": "Evaluator description",
-          "name": "description",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "config": {
-          "description": "Evaluator config as JSON string",
-          "name": "config",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "evaluators:create",
+      "id": "datasets:get-span",
       "pluginAlias": "@respan/cli",
       "pluginName": "@respan/cli",
       "pluginType": "core",
@@ -1059,20 +1087,20 @@
       "relativePath": [
         "dist",
         "commands",
-        "evaluators",
-        "create.js"
+        "datasets",
+        "get-span.js"
       ]
     },
-    "evaluators:get": {
+    "datasets:get": {
       "aliases": [],
       "args": {
         "id": {
-          "description": "Evaluator ID",
+          "description": "Dataset ID",
           "name": "id",
           "required": true
         }
       },
-      "description": "Get a specific evaluator",
+      "description": "Get a specific dataset",
       "flags": {
         "api-key": {
           "description": "API key (env: RESPAN_API_KEY)",
@@ -1111,7 +1139,7 @@
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "evaluators:get",
+      "id": "datasets:get",
       "pluginAlias": "@respan/cli",
       "pluginName": "@respan/cli",
       "pluginType": "core",
@@ -1121,14 +1149,14 @@
       "relativePath": [
         "dist",
         "commands",
-        "evaluators",
+        "datasets",
         "get.js"
       ]
     },
-    "evaluators:list": {
+    "datasets:list": {
       "aliases": [],
       "args": {},
-      "description": "List evaluators",
+      "description": "List datasets",
       "flags": {
         "api-key": {
           "description": "API key (env: RESPAN_API_KEY)",
@@ -1167,7 +1195,7 @@
         "limit": {
           "description": "Number of results per page",
           "name": "limit",
-          "default": 20,
+          "default": 50,
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
@@ -1183,7 +1211,7 @@
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "evaluators:list",
+      "id": "datasets:list",
       "pluginAlias": "@respan/cli",
       "pluginName": "@respan/cli",
       "pluginType": "core",
@@ -1193,20 +1221,20 @@
       "relativePath": [
         "dist",
         "commands",
-        "evaluators",
+        "datasets",
         "list.js"
       ]
     },
-    "evaluators:run": {
+    "datasets:spans": {
       "aliases": [],
       "args": {
-        "id": {
-          "description": "Evaluator ID",
-          "name": "id",
+        "dataset-id": {
+          "description": "Dataset ID",
+          "name": "dataset-id",
           "required": true
         }
       },
-      "description": "Run an evaluator",
+      "description": "List spans in a dataset",
       "flags": {
         "api-key": {
           "description": "API key (env: RESPAN_API_KEY)",
@@ -1241,32 +1269,11 @@
           "name": "verbose",
           "allowNo": false,
           "type": "boolean"
-        },
-        "dataset-id": {
-          "description": "Dataset ID to evaluate against",
-          "name": "dataset-id",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "log-ids": {
-          "description": "Comma-separated log/span IDs to evaluate",
-          "name": "log-ids",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "params": {
-          "description": "Additional parameters as JSON string",
-          "name": "params",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "evaluators:run",
+      "id": "datasets:spans",
       "pluginAlias": "@respan/cli",
       "pluginName": "@respan/cli",
       "pluginType": "core",
@@ -1276,20 +1283,20 @@
       "relativePath": [
         "dist",
         "commands",
-        "evaluators",
-        "run.js"
+        "datasets",
+        "spans.js"
       ]
     },
-    "evaluators:update": {
+    "datasets:update": {
       "aliases": [],
       "args": {
         "id": {
-          "description": "Evaluator ID",
+          "description": "Dataset ID",
           "name": "id",
           "required": true
         }
       },
-      "description": "Update an evaluator",
+      "description": "Update a dataset",
       "flags": {
         "api-key": {
           "description": "API key (env: RESPAN_API_KEY)",
@@ -1326,30 +1333,23 @@
           "type": "boolean"
         },
         "name": {
-          "description": "Evaluator name",
+          "description": "Dataset name",
           "name": "name",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
         "description": {
-          "description": "Evaluator description",
+          "description": "Dataset description",
           "name": "description",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
-        },
-        "config": {
-          "description": "Evaluator config as JSON string",
-          "name": "config",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "evaluators:update",
+      "id": "datasets:update",
       "pluginAlias": "@respan/cli",
       "pluginName": "@respan/cli",
       "pluginType": "core",
@@ -1359,7 +1359,7 @@
       "relativePath": [
         "dist",
         "commands",
-        "evaluators",
+        "datasets",
         "update.js"
       ]
     },
@@ -1671,6 +1671,28 @@
           "multiple": false,
           "type": "option"
         },
+        "customer-id": {
+          "description": "Customer/user identifier for traces (e.g. your name or email)",
+          "env": "RESPAN_CUSTOMER_ID",
+          "name": "customer-id",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "span-name": {
+          "description": "Root span name for traces (default: claude-code)",
+          "name": "span-name",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "workflow-name": {
+          "description": "Workflow name for traces (default: claude-code)",
+          "name": "workflow-name",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
         "dry-run": {
           "description": "Preview changes without writing files",
           "name": "dry-run",
@@ -1781,6 +1803,28 @@
           "multiple": false,
           "type": "option"
         },
+        "customer-id": {
+          "description": "Customer/user identifier for traces (e.g. your name or email)",
+          "env": "RESPAN_CUSTOMER_ID",
+          "name": "customer-id",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "span-name": {
+          "description": "Root span name for traces (default: claude-code)",
+          "name": "span-name",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "workflow-name": {
+          "description": "Workflow name for traces (default: claude-code)",
+          "name": "workflow-name",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
         "dry-run": {
           "description": "Preview changes without writing files",
           "name": "dry-run",
@@ -1891,6 +1935,28 @@
           "multiple": false,
           "type": "option"
         },
+        "customer-id": {
+          "description": "Customer/user identifier for traces (e.g. your name or email)",
+          "env": "RESPAN_CUSTOMER_ID",
+          "name": "customer-id",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "span-name": {
+          "description": "Root span name for traces (default: claude-code)",
+          "name": "span-name",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "workflow-name": {
+          "description": "Workflow name for traces (default: claude-code)",
+          "name": "workflow-name",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
         "dry-run": {
           "description": "Preview changes without writing files",
           "name": "dry-run",
@@ -2001,6 +2067,28 @@
           "multiple": false,
           "type": "option"
         },
+        "customer-id": {
+          "description": "Customer/user identifier for traces (e.g. your name or email)",
+          "env": "RESPAN_CUSTOMER_ID",
+          "name": "customer-id",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "span-name": {
+          "description": "Root span name for traces (default: claude-code)",
+          "name": "span-name",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "workflow-name": {
+          "description": "Workflow name for traces (default: claude-code)",
+          "name": "workflow-name",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
         "dry-run": {
           "description": "Preview changes without writing files",
           "name": "dry-run",
@@ -3370,5 +3458,5 @@
       ]
     }
   },
-  "version": "0.4.1"
+  "version": "0.5.0"
 }

package/package.json

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