---
title: "Basic Examples"
description: "Step-by-step basic examples for the TraceRTM Go SDK"
---

# Basic Examples

Step-by-step examples for common TraceRTM Go SDK operations.

## Hello World

The simplest possible TraceRTM program:

```go
package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "github.com/tracertm/tracertm-go"
)

func main() {
    client := tracertm.NewClient(os.Getenv("TRACERTM_API_KEY"))
    ctx := context.Background()

    // Verify connection
    user, err := client.Users.Me(ctx)
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Hello, %s!\n", user.Name)
}
```

---

## List All Projects

```go
package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "github.com/tracertm/tracertm-go"
)

func main() {
    client := tracertm.NewClient(os.Getenv("TRACERTM_API_KEY"))
    ctx := context.Background()

    projects, err := client.Projects.List(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Found %d projects:\n", len(projects.Data))
    for _, p := range projects.Data {
        fmt.Printf("  [%s] %s\n", p.Key, p.Name)
    }
}
```

---

## Create a New Project

```go
package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "github.com/tracertm/tracertm-go"
)

func main() {
    client := tracertm.NewClient(os.Getenv("TRACERTM_API_KEY"))
    ctx := context.Background()

    project, err := client.Projects.Create(ctx, &tracertm.CreateProjectInput{
        Name:        "My First Project",
        Key:         "MFP",
        Description: "Created with the Go SDK",
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Created project:\n")
    fmt.Printf("  ID: %s\n", project.ID)
    fmt.Printf("  Key: %s\n", project.Key)
    fmt.Printf("  Name: %s\n", project.Name)
}
```

---

## Create Items

### Create a Requirement

```go
package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "github.com/tracertm/tracertm-go"
)

func main() {
    client := tracertm.NewClient(os.Getenv("TRACERTM_API_KEY"))
    ctx := context.Background()

    projectID := "proj_your_project_id"

    requirement, err := client.Items.Create(ctx, projectID, &tracertm.CreateItemInput{
        Type:        "requirement",
        Title:       "User Login",
        Description: "Users must be able to log in with email and password",
        Priority:    "high",
        Tags:        []string{"auth", "security"},
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Created requirement: %s - %s\n", requirement.Key, requirement.Title)
}
```

### Create a Test Case

```go
testCase, err := client.Items.Create(ctx, projectID, &tracertm.CreateItemInput{
    Type:        "test_case",
    Title:       "Verify Login with Valid Credentials",
    Description: "Test that users can log in with correct email and password",
    Priority:    "high",
})
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Created test case: %s - %s\n", testCase.Key, testCase.Title)
```

### Create with Custom Fields

```go
item, err := client.Items.Create(ctx, projectID, &tracertm.CreateItemInput{
    Type:        "requirement",
    Title:       "Payment Processing",
    Description: "System must process payments securely",
    Priority:    "critical",
    Tags:        []string{"payment", "security"},
    CustomFields: map[string]interface{}{
        "story_points":   13,
        "epic":           "Checkout",
        "compliance":     "PCI-DSS",
        "estimated_days": 5,
    },
})
```

---

## List Items

### List All Items in a Project

```go
items, err := client.Items.List(ctx, projectID, nil)
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Found %d items:\n", len(items.Data))
for _, item := range items.Data {
    fmt.Printf("  [%s] %s (%s)\n", item.Key, item.Title, item.Type)
}
```

### List with Filters

```go
// List only high-priority requirements
items, err := client.Items.List(ctx, projectID, &tracertm.ListItemsOptions{
    Type:     "requirement",
    Priority: "high",
    Status:   "approved",
})

// List with pagination
items, err := client.Items.List(ctx, projectID, &tracertm.ListItemsOptions{
    Limit:  25,
    Offset: 0,
    Sort:   "created_at",
    Order:  "desc",
})
```

### Iterate Through All Items

```go
iter := client.Items.Iterate(ctx, projectID, nil)

for iter.Next() {
    item := iter.Item()
    fmt.Printf("%s: %s\n", item.Key, item.Title)
}

if err := iter.Err(); err != nil {
    log.Fatal(err)
}
```

---

## Update Items

### Simple Update

```go
item, err := client.Items.Update(ctx, "item_abc123", &tracertm.UpdateItemInput{
    Title: "Updated Title",
})
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Updated: %s\n", item.Title)
```

### Update Multiple Fields

```go
item, err := client.Items.Update(ctx, "item_abc123", &tracertm.UpdateItemInput{
    Title:       "Secure User Authentication",
    Description: "Enhanced security requirements for user login",
    Priority:    "critical",
    Tags:        []string{"auth", "security", "priority"},
})
```

---

## Create Links

### Link a Requirement to a Test Case

```go
link, err := client.Links.Create(ctx, &tracertm.CreateLinkInput{
    SourceID: requirementID,
    TargetID: testCaseID,
    LinkType: "verified_by",
})
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Created link: %s\n", link.ID)
```

### Common Link Types

```go
// Requirement verified by test case
client.Links.Create(ctx, &tracertm.CreateLinkInput{
    SourceID: requirementID,
    TargetID: testCaseID,
    LinkType: "verified_by",
})

// Requirement implemented by code
client.Links.Create(ctx, &tracertm.CreateLinkInput{
    SourceID: requirementID,
    TargetID: codeItemID,
    LinkType: "implemented_by",
})

// Item depends on another
client.Links.Create(ctx, &tracertm.CreateLinkInput{
    SourceID: itemID,
    TargetID: dependencyID,
    LinkType: "depends_on",
})

// Parent-child relationship
client.Links.Create(ctx, &tracertm.CreateLinkInput{
    SourceID: parentID,
    TargetID: childID,
    LinkType: "parent_of",
})
```

---

## List Links

```go
// List all links for a source item
links, err := client.Links.List(ctx, &tracertm.ListLinksInput{
    SourceID: itemID,
})

// List links of a specific type
links, err := client.Links.List(ctx, &tracertm.ListLinksInput{
    ProjectID: projectID,
    LinkType:  "verified_by",
})

// Print results
for _, link := range links.Data {
    fmt.Printf("%s -> %s (%s)\n", link.SourceID, link.TargetID, link.LinkType)
}
```

---

## Delete Items and Links

```go
// Delete a single item
err := client.Items.Delete(ctx, "item_abc123")
if err != nil {
    log.Fatal(err)
}

// Delete a link
err = client.Links.Delete(ctx, "link_abc123")
if err != nil {
    log.Fatal(err)
}

// Delete a project
err = client.Projects.Delete(ctx, "proj_abc123")
if err != nil {
    log.Fatal(err)
}
```

---

## Search Items

```go
results, err := client.Search.Items(ctx, &tracertm.SearchInput{
    Query:     "authentication",
    ProjectID: projectID,
    Limit:     10,
})
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Found %d results:\n", len(results.Data))
for _, result := range results.Data {
    fmt.Printf("  %s: %s (score: %.2f)\n", result.Key, result.Title, result.Score)
}
```

---

## Coverage Report

```go
coverage, err := client.Reports.Coverage(ctx, &tracertm.CoverageReportInput{
    ProjectID:  projectID,
    SourceType: "requirement",
    TargetType: "test_case",
})
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Coverage Report:\n")
fmt.Printf("  Total requirements: %d\n", coverage.TotalSources)
fmt.Printf("  Covered: %d\n", coverage.CoveredCount)
fmt.Printf("  Uncovered: %d\n", coverage.UncoveredCount)
fmt.Printf("  Coverage: %.1f%%\n", coverage.CoveragePercent)

if len(coverage.UncoveredItems) > 0 {
    fmt.Printf("\nUncovered requirements:\n")
    for _, item := range coverage.UncoveredItems {
        fmt.Printf("  - %s: %s\n", item.Key, item.Title)
    }
}
```

---

## Transition Item Status

```go
// Get available transitions
transitions, err := client.Items.AvailableTransitions(ctx, "item_abc123")
if err != nil {
    log.Fatal(err)
}

fmt.Println("Available transitions:")
for _, t := range transitions {
    fmt.Printf("  %s -> %s\n", t.Name, t.ToState)
}

// Transition the item
item, err := client.Items.Transition(ctx, "item_abc123", &tracertm.TransitionInput{
    Transition: "approve",
    Comment:    "Approved after review",
})
if err != nil {
    log.Fatal(err)
}

fmt.Printf("New status: %s\n", item.Status)
```

---

## Complete Example: Create Traceability

```go
package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "github.com/tracertm/tracertm-go"
)

func main() {
    client := tracertm.NewClient(os.Getenv("TRACERTM_API_KEY"))
    ctx := context.Background()

    // Get or create project
    projectID := "proj_your_project"

    // Create requirements
    requirements := []tracertm.CreateItemInput{
        {Type: "requirement", Title: "User Registration", Priority: "high"},
        {Type: "requirement", Title: "Password Reset", Priority: "medium"},
        {Type: "requirement", Title: "Session Management", Priority: "high"},
    }

    var reqIDs []string
    for _, req := range requirements {
        item, err := client.Items.Create(ctx, projectID, &req)
        if err != nil {
            log.Fatal(err)
        }
        reqIDs = append(reqIDs, item.ID)
        fmt.Printf("Created: %s\n", item.Key)
    }

    // Create test cases
    testCases := []tracertm.CreateItemInput{
        {Type: "test_case", Title: "Test: User can register"},
        {Type: "test_case", Title: "Test: User receives confirmation email"},
        {Type: "test_case", Title: "Test: Password reset link works"},
        {Type: "test_case", Title: "Test: Session expires after timeout"},
    }

    var tcIDs []string
    for _, tc := range testCases {
        item, err := client.Items.Create(ctx, projectID, &tc)
        if err != nil {
            log.Fatal(err)
        }
        tcIDs = append(tcIDs, item.ID)
        fmt.Printf("Created: %s\n", item.Key)
    }

    // Create links
    linkMappings := []struct {
        reqIdx int
        tcIdx  int
    }{
        {0, 0}, // Registration -> Test registration
        {0, 1}, // Registration -> Test confirmation email
        {1, 2}, // Password reset -> Test password link
        {2, 3}, // Session -> Test session timeout
    }

    for _, mapping := range linkMappings {
        _, err := client.Links.Create(ctx, &tracertm.CreateLinkInput{
            SourceID: reqIDs[mapping.reqIdx],
            TargetID: tcIDs[mapping.tcIdx],
            LinkType: "verified_by",
        })
        if err != nil {
            log.Fatal(err)
        }
    }

    fmt.Println("Created all links")

    // Generate coverage report
    coverage, err := client.Reports.Coverage(ctx, &tracertm.CoverageReportInput{
        ProjectID:  projectID,
        SourceType: "requirement",
        TargetType: "test_case",
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("\nCoverage: %.1f%% (%d/%d requirements covered)\n",
        coverage.CoveragePercent,
        coverage.CoveredCount,
        coverage.TotalSources)
}
```

---

## Related Documentation

- [Advanced Examples](/docs/api-reference/sdks/go/advanced-examples) - Complex scenarios
- [API Reference](/docs/api-reference/sdks/go/api-reference) - Complete API reference
- [Error Handling](/docs/api-reference/sdks/go/error-handling) - Handle errors properly
