Sessions Commands

Sessions commands work with both AIOBS and Langfuse providers. The available options vary by provider.

shepherd sessions list

List all sessions.

shepherd sessions list [OPTIONS]

Options:

Option

Short

Description

AIOBS

Langfuse

--output

-o

Output format: table or json

✅

✅

--limit

-n

Max sessions to display

✅

✅

--page

-p

Page number

❌

✅

--from

Filter after timestamp

❌

✅

--to

Filter before timestamp

❌

✅

--ids

Print only session IDs

✅

✅

Examples:

shepherd sessions list
shepherd sessions list -n 10
shepherd sessions list -o json
shepherd sessions list --ids

# Langfuse pagination
shepherd sessions list --page 2 -n 20
shepherd sessions list --from 2025-12-01

shepherd sessions get

Get session details.

shepherd sessions get <session-id> [OPTIONS]

Options:

Option

Short

Description

--output

-o

Output format: table or json

Examples:

shepherd sessions get be393d0d-7139-4241-a00d-e3c9ff4f9fcf
shepherd sessions get be393d0d-7139-4241-a00d-e3c9ff4f9fcf -o json

shepherd sessions diff (AIOBS only)

Compare two sessions and show their differences. This command is only available for AIOBS provider.

shepherd sessions diff <session-id1> <session-id2> [OPTIONS]

Arguments:

Argument

Description

SESSION_ID1

First session ID (baseline)

SESSION_ID2

Second session ID (comparison)

Options:

Option

Short

Description

--output

-o

Output format: table or json

What it compares:

  • Metadata: Duration, labels, meta fields

  • LLM Calls: Total calls, tokens (input/output/total), latency, errors

  • Provider Distribution: Calls per provider (OpenAI, Anthropic, etc.)

  • Model Distribution: Calls per model (gpt-4, claude-3, etc.)

  • Function Events: Total calls, unique functions, duration

  • Trace Structure: Trace depth, root nodes

  • Evaluations: Total, passed, failed, pass rate

  • System Prompts: Compares system prompts used in each session

  • Request Parameters: Temperature, max tokens, tools used, streaming

  • Responses: Content length, tool calls, stop reasons

Examples:

# Basic comparison
shepherd sessions diff abc123 def456

# Output as JSON
shepherd sessions diff abc123 def456 -o json

# Compare baseline vs experiment
shepherd sessions diff baseline-session-id experiment-session-id

# Explicit AIOBS command
shepherd aiobs sessions diff abc123 def456

Example Output:

╭───────────────────── Session Diff ─────────────────────╮
│ Session 1: abc12345... (baseline-agent)                │
│ Session 2: def67890... (updated-agent)                 │
╰────────────────────────────────────────────────────────╯

┏━━━━━━━━━━━ LLM Calls Summary ━━━━━━━━━━━┓
│ Metric        │ S1    │ S2    │ Delta   │
├───────────────┼───────┼───────┼─────────┤
│ Total Calls   │ 5     │ 8     │ +3      │
│ Total Tokens  │ 1,200 │ 1,800 │ +600    │
│ Avg Latency   │ 2.0s  │ 1.5s  │ -500ms  │
└───────────────┴───────┴───────┴─────────┘

⚠ System prompts differ between sessions

Tools Used:
  + Added: run_security_scan
  - Removed: search_code
  Common: get_file_contents

Explicit Provider Commands

Use provider-specific commands to bypass routing:

# AIOBS sessions
shepherd aiobs sessions list
shepherd aiobs sessions search --has-errors
shepherd aiobs sessions diff session1 session2

# Langfuse sessions
shepherd langfuse sessions list
shepherd langfuse sessions search --user-id alice
shepherd langfuse sessions get session-abc

Scripting

AIOBS Examples

# Process sessions in a loop
for sid in $(shepherd sessions list --ids -n 5); do
    shepherd sessions get "$sid" -o json > "session_${sid}.json"
done

# Pipe to jq
shepherd sessions list -o json | jq '.sessions[].name'

# Get latest session
LATEST=$(shepherd sessions list --ids -n 1)
shepherd sessions get "$LATEST"

# Find sessions with errors and export
for sid in $(shepherd sessions search --has-errors --ids); do
    shepherd sessions get "$sid" -o json > "error_session_${sid}.json"
done

# Search for production sessions with failed evals
shepherd sessions search -l env=production --evals-failed -o json | jq '.sessions'

# Compare latest two sessions
SESSIONS=($(shepherd sessions list --ids -n 2))
shepherd sessions diff "${SESSIONS[0]}" "${SESSIONS[1]}"

# Export diff to JSON for analysis
shepherd sessions diff session-v1 session-v2 -o json > diff_report.json

Langfuse Examples

# Process sessions in a loop
for sid in $(shepherd langfuse sessions list --ids -n 5); do
    shepherd langfuse sessions get "$sid" -o json > "session_${sid}.json"
done

# Pipe to jq
shepherd langfuse sessions list -o json | jq '.sessions[].id'

# Find expensive sessions
shepherd langfuse sessions search --min-cost 0.05 -o json

# Export user sessions
shepherd langfuse sessions search --user-id alice -o json > alice_sessions.json

# Get sessions with many traces
for sid in $(shepherd langfuse sessions search --min-traces 10 --ids); do
    echo "Session $sid has 10+ traces"
done