# Hatchet Go SDK Reference This is the Go SDK reference, documenting methods available for interacting with Hatchet resources. Check out the [user guide](/v1) for an introduction for getting your first tasks running. For complete, generated API documentation, see the [Go package docs on pkg.go.dev](https://pkg.go.dev/github.com/hatchet-dev/hatchet/sdks/go). By default, the client reads its configuration (token, host, TLS settings, and so on) from the `HATCHET_CLIENT_*` environment variables. Configuration can be overridden with client options such as `hatchet.WithToken`, `hatchet.WithHostPort`, and `hatchet.WithNamespace`. ## Client Client provides the main interface for interacting with Hatchet. Methods: Name, Description `Close`, Close shuts down the client. `Events`, Events returns a client for sending and managing events. `GetEngineVersion`, GetEngineVersion retrieves the engine version from the server. `NewStandaloneBatchTask`, NewStandaloneBatchTask creates a standalone batch task that can be triggered independently. `NewStandaloneDurableTask`, NewStandaloneDurableTask creates a standalone durable task that can be triggered independently. `NewStandaloneTask`, NewStandaloneTask creates a standalone task that can be triggered independently. `NewWorker`, NewWorker creates a worker that can execute workflows. `NewWorkflow`, NewWorkflow creates a new workflow definition. `Run`, Run executes a workflow with the provided input and waits for completion. `RunMany`, RunMany executes multiple workflow instances with different inputs. `RunNoWait`, RunNoWait executes a workflow with the provided input without waiting for completion. ### Feature clients The client exposes lazily-initialized [feature clients](/reference/go/feature-clients/cel) as methods: #### `CEL()` CEL returns a client for working with CEL expressions. See the [CEL client](/reference/go/feature-clients/cel). #### `Crons()` Crons returns a client for managing cron triggers. See the [Crons client](/reference/go/feature-clients/crons). #### `Filters()` Filters returns a client for managing event filters. See the [Filters client](/reference/go/feature-clients/filters). #### `Logs()` Logs returns a client for managing task logs. See the [Logs client](/reference/go/feature-clients/logs). #### `Metrics()` Metrics returns a feature client for interacting with workflow and task metrics. See the [Metrics client](/reference/go/feature-clients/metrics). #### `RateLimits()` RateLimits returns a client for managing rate limits. See the [Rate Limits client](/reference/go/feature-clients/ratelimits). #### `Runs()` Runs returns a client for managing workflow runs. See the [Runs client](/reference/go/feature-clients/runs). #### `Schedules()` Schedules returns a client for managing scheduled workflow runs. See the [Schedules client](/reference/go/feature-clients/schedules). #### `Webhooks()` Webhooks returns a client for managing webhooks. See the [Webhooks client](/reference/go/feature-clients/webhooks). #### `Workers()` Workers returns a client for managing workers. See the [Workers client](/reference/go/feature-clients/workers). #### `Workflows()` Workflows returns a client for managing workflow definitions. See the [Workflows client](/reference/go/feature-clients/workflows). ### Functions #### `NewClient` NewClient creates a new Hatchet client. Configuration options can be provided to customize the client behavior. ```go func NewClient(opts ...ClientOpt) (*Client, error) ``` Parameters: Name, Type `opts`, `...ClientOpt` Returns: Type `*Client` `error` #### `Close` Close shuts down the client. It is a no-op unless the client runs in embedded mode, in which case it shuts down the in-process engine. ```go func (c *Client) Close(ctx context.Context) error ``` Parameters: Name, Type `ctx`, `context.Context` Returns: Type `error` #### `Events` Events returns a client for sending and managing events. ```go func (c *Client) Events() EventClient ``` Returns: Type `EventClient` #### `GetEngineVersion` GetEngineVersion retrieves the engine version from the server. ```go func (c *Client) GetEngineVersion(ctx context.Context) (string, error) ``` Parameters: Name, Type `ctx`, `context.Context` Returns: Type `string` `error` #### `NewStandaloneBatchTask` NewStandaloneBatchTask creates a standalone batch task that can be triggered independently. This is a specialized workflow containing only one batch task, making it easier to create simple single-task workflows without the workflow boilerplate. The function parameter must have the signature: ```go func(ctx hatchet.Context, input map[string]T) (map[string]R, error) ``` or, when batch.BroadcastOutput is true: ```go func(ctx hatchet.Context, input map[string]T) (R, error) ``` Function signatures are validated at runtime using reflection. Options can be any combination of WorkflowOption and TaskOption. Preview: batch tasks are in beta and may change in future releases. ```go func (c *Client) NewStandaloneBatchTask(name string, fn any, batch BatchConfig, options ...StandaloneTaskOption) *StandaloneTask ``` Parameters: Name, Type `name`, `string` `fn`, `any` `batch`, `BatchConfig` `options`, `...StandaloneTaskOption` Returns: Type `*StandaloneTask` #### `NewStandaloneDurableTask` NewStandaloneDurableTask creates a standalone durable task that can be triggered independently. This is a specialized workflow containing only one durable task, making it easier to create simple single-task workflows with durable functionality. The function parameter must have the signature: ```go func(ctx hatchet.DurableContext, input any) (any, error) ``` Function signatures are validated at runtime using reflection. Options can be any combination of WorkflowOption and TaskOption. ```go func (c *Client) NewStandaloneDurableTask(name string, fn any, options ...StandaloneTaskOption) *StandaloneTask ``` Parameters: Name, Type `name`, `string` `fn`, `any` `options`, `...StandaloneTaskOption` Returns: Type `*StandaloneTask` #### `NewStandaloneTask` NewStandaloneTask creates a standalone task that can be triggered independently. This is a specialized workflow containing only one task, making it easier to create simple single-task workflows without the workflow boilerplate. The function parameter must have the signature: ```go func(ctx hatchet.Context, input any) (any, error) ``` Function signatures are validated at runtime using reflection. Options can be any combination of WorkflowOption and TaskOption. ```go func (c *Client) NewStandaloneTask(name string, fn any, options ...StandaloneTaskOption) *StandaloneTask ``` Parameters: Name, Type `name`, `string` `fn`, `any` `options`, `...StandaloneTaskOption` Returns: Type `*StandaloneTask` #### `NewWorker` NewWorker creates a worker that can execute workflows. ```go func (c *Client) NewWorker(name string, options ...WorkerOption) (*Worker, error) ``` Parameters: Name, Type `name`, `string` `options`, `...WorkerOption` Returns: Type `*Worker` `error` #### `NewWorkflow` NewWorkflow creates a new workflow definition. Workflows can be configured with triggers, events, and other options. ```go func (c *Client) NewWorkflow(name string, options ...WorkflowOption) *Workflow ``` Parameters: Name, Type `name`, `string` `options`, `...WorkflowOption` Returns: Type `*Workflow` #### `Run` Run executes a workflow with the provided input and waits for completion. ```go func (c *Client) Run(ctx context.Context, workflowName string, input any, opts ...RunOptFunc) (*WorkflowResult, error) ``` Parameters: Name, Type `ctx`, `context.Context` `workflowName`, `string` `input`, `any` `opts`, `...RunOptFunc` Returns: Type `*WorkflowResult` `error` #### `RunMany` RunMany executes multiple workflow instances with different inputs. The returned results are in the same order as the inputs. Returns workflow run IDs that can be used to track the run statuses. ```go func (c *Client) RunMany(ctx context.Context, workflowName string, inputs []RunManyOpt) ([]WorkflowRunRef, error) ``` Parameters: Name, Type `ctx`, `context.Context` `workflowName`, `string` `inputs`, `[]RunManyOpt` Returns: Type `[]WorkflowRunRef` `error` #### `RunNoWait` RunNoWait executes a workflow with the provided input without waiting for completion. Returns a workflow run reference that can be used to track the run status. ```go func (c *Client) RunNoWait(ctx context.Context, workflowName string, input any, opts ...RunOptFunc) (*WorkflowRunRef, error) ``` Parameters: Name, Type `ctx`, `context.Context` `workflowName`, `string` `input`, `any` `opts`, `...RunOptFunc` Returns: Type `*WorkflowRunRef` `error` ## Worker Worker represents a worker that can execute workflows. Methods: Name, Description `Start`, Starts the worker instance and returns a cleanup function. `StartBlocking`, StartBlocking starts the worker and blocks until it completes. `Use`, Use registers middleware functions on the worker. ### Functions #### `Start` Starts the worker instance and returns a cleanup function. ```go func (w *Worker) Start() (func() error, error) ``` Returns: Type `func() error` `error` #### `StartBlocking` StartBlocking starts the worker and blocks until it completes. This is a convenience method for common usage patterns. ```go func (w *Worker) StartBlocking(ctx context.Context) error ``` Parameters: Name, Type `ctx`, `context.Context` Returns: Type `error` #### `Use` Use registers middleware functions on the worker. Middleware functions are called in order for each step run execution. ```go func (w *Worker) Use(mws ...MiddlewareFunc) ``` Parameters: Name, Type `mws`, `...MiddlewareFunc` ## Worker options Options for `Client.NewWorker`: Name, Signature, Description `WithDurableSlots`, `WithDurableSlots(durableSlots int)`, WithDurableSlots sets the maximum number of concurrent durable task runs. `WithLabels`, `WithLabels(labels map[string]any)`, WithLabels assigns labels to the worker for task routing. `WithLogger`, `WithLogger(logger *zerolog.Logger)`, WithLogger sets a custom logger for the worker. `WithPanicHandler`, `WithPanicHandler(panicHandler func(ctx Context, recovered any))`, WithPanicHandler sets a custom panic handler for the worker. `WithSlots`, `WithSlots(slots int)`, WithSlots sets the maximum number of concurrent workflow runs. `WithWorkflows`, `WithWorkflows(workflows ...WorkflowBase)`, WithWorkflows registers workflows and standalone tasks with the worker.