# 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 from the `github.com/hatchet-dev/hatchet/pkg/client` package, such as `WithToken`, `WithHostPort`, and `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](./feature-clients/cel) as methods: #### `CEL()` CEL returns a client for working with CEL expressions. See the [CEL client](./feature-clients/cel). #### `Crons()` Crons returns a client for managing cron triggers. See the [Crons client](./feature-clients/crons). #### `Filters()` Filters returns a client for managing event filters. See the [Filters client](./feature-clients/filters). #### `Logs()` Logs returns a client for managing task logs. See the [Logs client](./feature-clients/logs). #### `Metrics()` Metrics returns a feature client for interacting with workflow and task metrics. See the [Metrics client](./feature-clients/metrics). #### `RateLimits()` RateLimits returns a client for managing rate limits. See the [Rate Limits client](./feature-clients/ratelimits). #### `Runs()` Runs returns a client for managing workflow runs. See the [Runs client](./feature-clients/runs). #### `Schedules()` Schedules returns a client for managing scheduled workflow runs. See the [Schedules client](./feature-clients/schedules). #### `Webhooks()` Webhooks returns a client for managing webhooks. See the [Webhooks client](./feature-clients/webhooks). #### `Workers()` Workers returns a client for managing workers. See the [Workers client](./feature-clients/workers). #### `Workflows()` Workflows returns a client for managing workflow definitions. See the [Workflows client](./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 ...client.ClientOpt) (*Client, error) ``` Parameters: Name, Type `opts`, `...client.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() client.EventClient ``` Returns: Type `client.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. 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 ...worker.MiddlewareFunc) ``` Parameters: Name, Type `mws`, `...worker.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.