Getting Started

This guide will help you get started with Go Cursor SDK in just a few minutes.

Prerequisites

• Go 1.19 or higher
• Cursor IDE installed on your system

Installation

Install the SDK using go get:

go get github.com/vibe-coding-labs/go-cursor-sdk

Your First Program

Create a new Go file and import the SDK:

package main

import (
    "fmt"
    "log"
    
    cursor "github.com/vibe-coding-labs/go-cursor-sdk"
)

func main() {
    // Create a client with default configuration
    client, err := cursor.NewCursorClient(nil)
    if err != nil {
        log.Fatal(err)
    }
    defer client.Close()
    
    // List all sessions
    sessions, err := client.Sessions().ListSessions()
    if err != nil {
        log.Fatal(err)
    }
    
    fmt.Printf("Found %d sessions\n", len(sessions))
    
    // Print first session
    if len(sessions) > 0 {
        session := sessions[0]
        fmt.Printf("Latest session: %s\n", session.Title)
        fmt.Printf("Created at: %s\n", session.CreatedAt)
        fmt.Printf("Messages: %d\n", len(session.Messages))
    }
}

Run the program:

go run main.go

Configuration

You can customize the client behavior with ClientConfig:

config := &cursor.ClientConfig{
    EnableCache: true,                    // Enable caching
    CacheTTL:    5 * time.Minute,        // Cache TTL
    LogLevel:    cursor.LogLevelInfo,    // Log level
    CustomPath:  "/custom/path",         // Custom storage path (optional)
}

client, err := cursor.NewCursorClient(config)

Configuration Options

Option	Type	Description	Default
EnableCache	bool	Enable caching for better performance	false
CacheTTL	time.Duration	Cache time-to-live	5 minutes
EnableWatcher	bool	Enable data change watching	false
LogLevel	LogLevel	Logging level	LogLevelInfo
CustomPath	string	Custom Cursor storage path	Auto-detected
Logger	Logger	Custom logger implementation	Default logger

Basic Operations

Reading Sessions

// List all sessions
sessions, err := client.Sessions().ListSessions()

// Get a specific session
session, err := client.Sessions().GetSession("session-id")

// Search sessions
sessions, err := client.Sessions().SearchSessions("bug fix")

// Get sessions by time range
sessions, err := client.Sessions().GetSessionsByTimeRange(startTime, endTime)

Reading Statistics

// Get daily statistics
stats, err := client.Stats().GetDailyStats(time.Now())

// Get statistics for a date range
stats, err := client.Stats().GetStatsRange(startDate, endDate)

// Get total statistics
total, err := client.Stats().GetTotalStats()

Reading Composer Data

// List all composers
composers, err := client.Composers().ListComposers()

// Get a specific composer
composer, err := client.Composers().GetComposer("composer-id")

// List archived composers
archived, err := client.Composers().ListArchivedComposers()

Error Handling

The SDK provides specific error types for different scenarios:

sessions, err := client.Sessions().ListSessions()
if err != nil {
    switch e := err.(type) {
    case *cursor.PathNotFoundError:
        fmt.Printf("Path not found: %s\n", e.Path)
    case *cursor.PermissionError:
        fmt.Printf("Permission error: %s\n", e.Message)
    case *cursor.DatabaseError:
        fmt.Printf("Database error: %s\n", e.Message)
    default:
        fmt.Printf("Unknown error: %v\n", err)
    }
    return
}

Resource Management

Always close the client when done to release resources:

client, err := cursor.NewCursorClient(config)
if err != nil {
    log.Fatal(err)
}
defer client.Close() // Ensure resources are released

You can also check if the client is closed:

if client.IsClosed() {
    fmt.Println("Client is closed")
}

Next Steps

Now that you have the basics, explore more features:

• Unified Client - Learn about the client architecture
• Readers - Understand different data readers
• Query Builder - Build complex queries
• Examples - See practical examples
• API Reference - Complete API documentation