Configuration

A client needs a Smarter API key and the url of your Smarter platform. Every option of smarter.NewClient(...) is optional, because each value is looked up in this order:

  1. the options of smarter.NewClient(...),

  2. environment variables,

  3. the Smarter CLI’s configuration file, ~/.smarter/config.yaml,

  4. the defaults: the prod environment of platform.smarter.sh.

This is the lookup of every Smarter SDK and of the CLI itself, so the same environment configures them all.

client, err := smarter.NewClient(
    smarter.WithAPIKey("your 64-character Smarter api key"),
    smarter.WithBaseURL("https://platform.example.com"),
    smarter.WithTimeout(60*time.Second),
    smarter.WithMaxRetries(2),
)

NewClient returns a *smarter.ConfigurationError when there is no API key, or a value is invalid. A client is safe for concurrent use: create one, and share it.

API keys

An API key belongs to a user of an account, and the SDK can do whatever that user can do. Create one in the web console, or with a SmarterAuthToken manifest. See Authentication. Keep it out of your source code: use an environment variable or a secret manager.

Environment variables

Variable

Meaning

SMARTER_API_KEY

The API key.

SMARTER_BASE_URL

Your platform’s url, e.g. https://platform.example.com or http://localhost:9357. The API’s path, /api/v1/, is added for you.

SMARTER_ENVIRONMENT

local, alpha, beta, next or prod: which environment of the CLI’s configuration file to use, and how to derive the url when there is no base url.

SMARTER_ROOT_DOMAIN

The platform’s root domain, e.g. platform.example.com, for deriving the url.

SMARTER_TIMEOUT

Seconds to wait for a response, as in every Smarter SDK. The default is 60, because a prompt that calls several tools can take tens of seconds.

SMARTER_MAX_RETRIES

How many times to retry a request that failed for a transient reason. The default is 2.

SMARTER_LOG

info logs each request to stderr, and debug its body too. API keys are never logged. See Errors and Reliability.

SMARTER_CONFIG_FILE

Another path for the CLI’s configuration file.

Without a base url, the url is derived from the environment, exactly as the CLI derives it: local is http://localhost:9357, alpha, beta and next are https://<environment>.<root domain>, and prod is https://<root domain>. smarter.EnvironmentURL derives it for you.

Sharing the CLI’s configuration

smarter configure writes the CLI’s configuration file, with an API key per environment:

config:
  environment: local
  root_domain: platform.example.com
local:
  api_key: <your local api key>
prod:
  api_key: <your production api key>

The SDK reads it too, so smarter.NewClient() connects to the CLI’s current environment, with that environment’s key, and smarter.NewClient(smarter.WithEnvironment(smarter.EnvironmentProd)) to another one.

Your own HTTP client

Pass an *http.Client to send requests through a corporate proxy, with custom TLS settings, or through a test RoundTripper. Leave its Timeout at 0: the SDK applies its own timeout to each attempt.

proxy, _ := url.Parse("http://proxy.example.com:3128")
client, err := smarter.NewClient(smarter.WithHTTPClient(&http.Client{
    Transport: &http.Transport{Proxy: http.ProxyURL(proxy)},
}))

smarter.WithHeader adds a header to every request, and smarter.WithLookupEnv replaces the function that reads environment variables, e.g. in a test.