Initializing the client
Use hatchet.NewClient() to create a client instance. It reads HATCHET_CLIENT_TOKEN from the environment automatically:
package main
import (
"log"
hatchet "github.com/hatchet-dev/hatchet/sdks/go"
)
func main() {
client, err := hatchet.NewClient()
if err != nil {
log.Fatal(err)
}
_ = client
}
ClientOpt functions to override specific settings:
import (
hatchet "github.com/hatchet-dev/hatchet/sdks/go"
v0Client "github.com/hatchet-dev/hatchet/pkg/client"
)
client, err := hatchet.NewClient(
v0Client.WithToken("ey..."),
v0Client.WithHostPort("localhost", 7070),
v0Client.WithNamespace("my-app"),
)
Signature
func NewClient(opts ...v0Client.ClientOpt) (*Client, error)
ClientOpt functions
Sets the API token directly, bypassing the HATCHET_CLIENT_TOKEN environment variable.
WithHostPort(host string, port int)
Sets the gRPC server address, e.g. WithHostPort("localhost", 7070). Overrides the address embedded in the token.
WithNamespace(namespace string)
Applies a namespace prefix to all workflow names and event keys. Can also be set via HATCHET_CLIENT_NAMESPACE.
Sets the log level for the SDK’s internal logger. Accepts any level string recognized by zerolog.
WithTenantId(tenantId string)
Overrides the tenant ID extracted from the JWT.
WithSharedMeta(meta map[string]string)
Attaches key-value metadata to every workflow run triggered by this client.
Adds custom headers to every outgoing gRPC request.
Feature clients
All feature clients are lazy-initialized properties on *Client. Each wraps a specific area of the Hatchet API.
| Method | Type | Description |
|---|
client.Metrics() | *MetricsClient | Workflow and queue metrics. |
client.RateLimits() | *RateLimitsClient | Manage rate limit configurations. |
client.Crons() | *CronsClient | Create and manage cron workflow triggers. |
client.Schedules() | *SchedulesClient | Create and manage one-off scheduled runs. |
client.Filters() | *FiltersClient | Create and manage event filters. |
client.Runs() | *RunsClient | Get, list, cancel, replay, and stream workflow runs. |
client.Workers() | *WorkersClient | List and inspect registered workers. |
client.Workflows() | *WorkflowsClient | List and get workflow definitions. |
client.Logs() | *LogsClient | Access task run log lines. |
client.Webhooks() | *WebhooksClient | Create and manage webhook endpoints. |
client.CEL() | *CELClient | Evaluate CEL expressions. |
client.Events() | EventClient | Push events that trigger event-based workflows. |
RunsClient
// Get a workflow run by ID
run, err := client.Runs().Get(ctx, runId)
// Get just the status
status, err := client.Runs().GetStatus(ctx, runId)
// List runs with filters
list, err := client.Runs().List(ctx, rest.V1WorkflowRunListParams{...})
// Cancel a task in a run
cancelled, err := client.Runs().Cancel(ctx, rest.V1CancelTaskRequest{...})
// Replay a task in a run
replayed, err := client.Runs().Replay(ctx, rest.V1ReplayTaskRequest{...})
// Subscribe to a streaming run
ch := client.Runs().SubscribeToStream(ctx, workflowRunId)
for msg := range ch {
fmt.Println(msg)
}
CronsClient
// Create a cron trigger
cron, err := client.Crons().Create(ctx, "my-workflow", features.CreateCronTrigger{
Name: "daily-report",
Expression: "0 9 * * *",
Input: map[string]interface{}{"report": "full"},
})
// List cron triggers
list, err := client.Crons().List(ctx, rest.CronWorkflowListParams{})
// Get a specific cron trigger
cron, err := client.Crons().Get(ctx, cronId)
// Delete a cron trigger
err = client.Crons().Delete(ctx, cronId)
SchedulesClient
// Schedule a one-off run
scheduled, err := client.Schedules().Create(ctx, "my-workflow", features.CreateScheduledRunTrigger{
TriggerAt: time.Now().Add(24 * time.Hour),
Input: map[string]interface{}{"key": "value"},
})
// List scheduled runs
list, err := client.Schedules().List(ctx, rest.WorkflowScheduledListParams{})
// Delete a scheduled run
err = client.Schedules().Delete(ctx, scheduledRunId)
MetricsClient
// Workflow-level metrics
metrics, err := client.Metrics().GetWorkflowMetrics(ctx, "my-workflow", nil)
// Tenant queue metrics
queueMetrics, err := client.Metrics().GetQueueMetrics(ctx, nil)
// Step run queue metrics
taskMetrics, err := client.Metrics().GetTaskQueueMetrics(ctx)
Events
err := client.Events().Push(ctx, "user:created", map[string]interface{}{
"userId": "123",
})
Error handling
NewClient and all feature client methods return a standard Go error as the second return value. Check it before using the result:
client, err := hatchet.NewClient()
if err != nil {
log.Fatalf("failed to create client: %v", err)
}
run, err := client.Runs().Get(ctx, runId)
if err != nil {
return fmt.Errorf("could not get run: %w", err)
}
NewClient returns an error if HATCHET_CLIENT_TOKEN is not set or if the token is not a valid JWT.
