Configuration

The Go SDK is configured via toggly.Config.

User context belongs to each request

Boolean evaluation and catalog-local variant assignment both use definitions fetched once. Prefer ambient request context (togglyhttp / WithEvalContext) or a worker default (Config.Identity / SetIdentity). Do not rebuild {Identity: …} on every call, and do not swap a shared client's identity per concurrent HTTP user.

Identity precedence (first non-empty wins): per-call override → ambient HTTP/session → Config.Identity / SetIdentity → empty. Groups come only from ambient or per-call Context.

Required

• AppKey: your application key from Toggly
• Environment: environment name (e.g. Production, Staging)

client, err := toggly.NewClient(toggly.Config{
  AppKey:      os.Getenv("TOGGLY_APP_KEY"),
  Environment: os.Getenv("TOGGLY_ENV"),
})

Feature variants (catalog-local)

Variants assign locally from definitions (variants + allocation). There is no EnableVariants toggle and no evaluated-variants-signed rail. Requires Go SDK 0.10+ for Config.Identity / SetIdentity.

HTTP / middleware (preferred)

After togglyhttp (or any middleware that stores eval context on r.Context()), pass an empty per-call Context:

v, err := client.GetVariant(r.Context(), "checkout-flow", toggly.Context{})
if err != nil {
    return err
}
if v != nil {
    _ = v.Name
    _ = v.ConfigurationValue
}

CLI / worker

Set identity once at startup (or when the session begins):

client, err := toggly.NewClient(toggly.Config{
    AppKey:      "YOUR_APP_KEY",
    Environment: "Production",
    Identity:    "user-123", // optional default
})
if err != nil {
    return err
}
defer client.Close()

client.SetIdentity("user-123")
v, err := client.GetVariant(ctx, "checkout-flow", toggly.Context{})

GetVariant returns (nil, nil) when the feature is unknown, has no catalog variants, or no allocation match. Pass a non-empty per-call Context only to override ambient or client identity (for example impersonation). Initialization is asynchronous; results become available after the first successful definitions refresh.

Common options

• BaseURL: defaults to https://app.toggly.io/ (gRPC usage and metrics)
• DefinitionsURL: defaults to https://definitions.toggly.io/ (HTTP definition fetches)
• RefreshInterval: background refresh period (default: 5 minutes)
• HTTPTimeout: timeout for refresh calls (default: 10 seconds)
• EnableUndefinedOnDevelopment: if true, unknown flags evaluate to true (useful for local dev)
• DisableEntityContextRegistration: if true, skip the startup PUT sdk/{appKey}/contexts catalog sync (entity evaluation still works; see Entity context)

client, err := toggly.NewClient(toggly.Config{
  AppKey:          "YOUR_APP_KEY",
  Environment:     "Production",
  BaseURL:         "https://app.toggly.io/",
  DefinitionsURL:  "https://definitions.toggly.io/",

  RefreshInterval: 2 * time.Minute,
  HTTPTimeout:     5 * time.Second,
})

Background refresh

The client starts its initial refresh asynchronously, then refreshes definitions in the background. Normally leave background refresh enabled. Disabling it also prevents the initial fetch and snapshot loading:

client, err := toggly.NewClient(toggly.Config{
  AppKey:                  "YOUR_APP_KEY",
  Environment:             "Production",
  DisableBackgroundRefresh: true,
})

There is no public manual refresh or wait-for-sync method. A successfully constructed client does not prove definitions are loaded. Use the status fields and loading/fallback guidance in Troubleshooting.

Session stickiness

SessionStore is optional. Use it if you want to cache evaluations per identity (or if you register custom non-deterministic filters and want stable decisions for a period of time):

client, err := toggly.NewClient(toggly.Config{
  AppKey:       "YOUR_APP_KEY",
  Environment:  "Production",
  SessionStore: session.NewMemoryStore(),
  SessionTTL:   30 * time.Minute,
})

Close / shutdown

Close the client exactly once from its owning component after request work stops, to stop background refresh and close optional gRPC connections. Do not close a shared client from individual request handlers. Close waits for the refresh goroutine and does not accept a cancellation context:

defer func() { _ = client.Close() }()