Clientlog CLI

A command-line interface for the Clientlog observability platform. Provides developer-friendly access to user session data, event streams, and analytical insights without requiring dashboard access.

Installation

From Source (Development)

git clone <repository>
cd clientlog/cli
pip install -e .

From PyPI (Future)

pip install clientlog-cli

Quick Start

1. Login

# Login with your Clientlog account email
clientlog login user@example.com

The CLI automatically discovers authentication configuration via .well-known/openid_configuration.

2. Search Sessions

# Find recent sessions for debugging
clientlog sessions search --origin https://example.com --project main --hours-back 2

# Search by tags (when available)
clientlog sessions search --origin https://example.com --project main --include-tags converted

3. Watch Live Events

# Monitor events in real-time
clientlog events watch --origin https://example.com --project main

# Watch specific session
clientlog events watch --origin https://example.com --project main --session abc123def

4. Trigger Processing

# Manually trigger session aggregation
clientlog trigger aggregation --origin https://example.com --project main --hours-back 24

# Send notifications
clientlog trigger notification --origin https://example.com --project main --method email

Commands

Health Check

# Check system health
clientlog status health

# JSON output
clientlog status health --json

Authentication

clientlog login <email>           # Login with email/password

Session Management

# Search sessions by criteria
clientlog sessions search --origin <url> --project <name> [options]
  --hours-back <hours>            # Time window (default: 24)
  --include-tags <tag1> <tag2>    # Include sessions with tags
  --exclude-tags <tag1> <tag2>    # Exclude sessions with tags  
  --limit <number>                # Max results (default: 50)
  --format table|json|csv         # Output format (default: table)

# List recent sessions
clientlog sessions list --origin <url> --project <name> [--limit <number>]

Event Monitoring

# Watch live events (polling)
clientlog events watch --origin <url> --project <name> [options]
  --interval <seconds>            # Polling interval (default: 5)
  --session <session_id>          # Filter by session
  --enriched                      # Show enriched events

# List recent events
clientlog events list --origin <url> --project <name> [options]
  --limit <number>                # Max results (default: 50)
  --enriched                      # Show enriched events

Processing Triggers

# Trigger session/event aggregation
clientlog trigger aggregation --origin <url> --project <name> [options]
  --hours-back <hours>            # Data window (default: 24)

# Trigger notifications
clientlog trigger notification --origin <url> --project <name> [options]
  --method email|slack            # Notification method (default: email)
  --hours-back <hours>            # Data window (default: 1)

# Trigger transition matrix computation
clientlog trigger transitions --origin <url> --project <name> [options]
  --hours-back <hours>            # Data window (default: 24)
  --min-sessions <number>         # Minimum sessions (default: 2)
  --min-probability <float>       # Minimum transition probability (default: 0.01)

Tag Management (Coming Soon)

# List available tags
clientlog tags list --origin <url> --project <name>

# Manage classification rules
clientlog tags rules --list
clientlog tags rules --apply

Configuration

Authentication Storage

The CLI stores authentication tokens in ~/.clientlog/auth.json and caches configuration in ~/.clientlog/config.json.

Environment Variables

export CLIENTLOG_API_URL="https://api.clientlog.example.com/v1"
export CLIENTLOG_AUTH_DOMAIN="auth.clientlog.example.com"

Configuration Discovery

The CLI automatically discovers authentication configuration from your Clientlog deployment's .well-known/openid_configuration endpoint, eliminating the need for manual configuration.

Output Formats

Table Format (Default)

Session ID           Start Time           Events   Duration   Tags
--------------------------------------------------------------------------------
abc123def456789012   2024-01-15 14:30    12       45.2s      converted, mobile
def456abc789012345   2024-01-15 14:28    8        23.1s      explore

JSON Format

{
  "sessions": [
    {
      "session": "abc123def456789012",
      "start_time": 1705329000000,
      "end_time": 1705329045200,
      "num_events": 12,
      "duration": 45200,
      "tags": ["converted", "mobile"]
    }
  ]
}

CSV Format

session,start_time,end_time,num_events,duration,tags
abc123def456789012,2024-01-15T14:30:00Z,2024-01-15T14:30:45Z,12,45200,"converted,mobile"

Common Workflows

Debug User Issue

# 1. Find recent sessions for the user's project
clientlog sessions search --origin https://myapp.com --project prod --hours-back 2

# 2. Watch events for a specific session
clientlog events watch --origin https://myapp.com --project prod --session <session_id>

# 3. View enriched events for detailed analysis
clientlog events list --origin https://myapp.com --project prod --enriched --limit 20

Monitor Deployment

# Watch live events during deployment
clientlog events watch --origin https://myapp.com --project prod --interval 3

# Trigger processing after deployment
clientlog trigger aggregation --origin https://myapp.com --project prod

Analyze User Behavior

# Search for converted sessions
clientlog sessions search --origin https://myapp.com --project prod --include-tags converted

# Generate transition matrices for flow analysis
clientlog trigger transitions --origin https://myapp.com --project prod --min-sessions 10

Dependencies

• Python 3.8+
• requests - HTTP client
• pydantic - Data validation

Note: No AWS SDK dependencies required. All API communication uses standard HTTP/OAuth2.

Development

Project Structure

cli/
├── clientlog_cli/
│   ├── auth.py          # Authentication management
│   ├── api.py           # HTTP client wrapper
│   ├── main.py          # CLI entry point
│   ├── commands/        # Command implementations
│   │   ├── sessions.py  # Session search/list
│   │   ├── events.py    # Event monitoring
│   │   ├── trigger.py   # Processing triggers
│   │   └── tags.py      # Tag management (stub)
│   └── models/          # Request/response models
│       └── requests.py  # API request models
├── setup.py
└── requirements.txt

Adding Commands

1. Create command module in clientlog_cli/commands/
2. Implement setup_parser(parser) and handle(args) functions
3. Register in main.py
4. Add request models to models/requests.py if needed

Testing

# Install in development mode
pip install -e .

# Test authentication
clientlog login test@example.com

# Test session search
clientlog sessions search --origin https://demo.example.com --project test