Nobl9 tools configuration

Reading time: 0 minute(s) (0 words)

All Nobl9 tools use the configuration model provided by the Nobl9 SDK for Go. The model resolves authentication, API, Project, and context settings from tool options, environment variables, a shared config.toml file, and defaults. Each tool can add settings or use a different environment-variable prefix.

Configuration file

The default configuration path is ~/.config/nobl9/config.toml. If the file does not exist, the shared configuration loader creates it. Use a tool option or <PREFIX>CONFIG_FILE_PATH to select another file. Use a no-config-file option or <PREFIX>NO_CONFIG_FILE=true to prevent file reads and creation.

A configuration file contains global settings and one or more named contexts. The defaultContext value selects the context when the tool does not specify one.

Minimal config.toml example

Create a user access key or API key, then enter its client ID and client secret. Choose your Nobl9 instance to show the required authentication settings.

Choose your Nobl9 instance app.nobl9.comus1.nobl9.com

config.toml

defaultContext = "default"

[contexts.default]
clientId = "YOUR_CLIENT_ID"
clientSecret = "YOUR_CLIENT_SECRET"
project = "default"

Complete config.toml example

The following example includes all supported fields and a second context. Most configurations do not need every field. Choose your Nobl9 instance to show its authorization settings.

Choose your Nobl9 instance app.nobl9.comus1.nobl9.com

config.toml

defaultContext = "production"

[sloctl]
filesPromptEnabled = true
filesPromptThreshold = 23

[contexts]
[contexts.production]
clientId = "YOUR_CLIENT_ID"
clientSecret = "YOUR_CLIENT_SECRET"
accessToken = "MANAGED_ACCESS_TOKEN"
project = "default"
oktaOrgURL = "https://accounts.nobl9.com"
oktaAuthServer = "auseg9kiegWKEtJZC416"
timeout = "10s"
caCertFile = "/path/to/ca-bundle.pem"

[contexts.development]
clientId = "ANOTHER_CLIENT_ID"
clientSecret = "ANOTHER_CLIENT_SECRET"
project = "default"
oktaOrgURL = "https://accounts.nobl9.com"
oktaAuthServer = "auseg9kiegWKEtJZC416"

Do not set accessToken manually for normal client ID and secret authentication. Nobl9 tools manage this value and can replace it when they refresh the token.

Global fields

Field	Default	Description
defaultContext	default	Context used when the tool does not select one.

sloctl fields

Set these fields in the [sloctl] section of config.toml.

Field	Default	Description
filesPromptEnabled	true	Enables the confirmation prompt for large file operations in sloctl.
filesPromptThreshold	23	Number of files that triggers the confirmation prompt in sloctl.

Context fields

Set these fields in the [contexts.<context-name>] section of config.toml.

Field	Default	Description
clientId	-	Client ID from a user access key or API key. Required with clientSecret when no usable token exists.
clientSecret	-	Client secret from a user access key or API key. Required with clientId when no usable token exists.
accessToken	-	Cached access token. Nobl9 tools manage this field during normal authentication.
project	default	Default Nobl9 Project for operations that do not select a Project.
oktaOrgURL	https://accounts.nobl9.com	Authorization service URL. The US instance requires its US-specific value.
oktaAuthServer	auseg9kiegWKEtJZC416	Authorization server ID. The US instance requires its US-specific value.
timeout	10s	Timeout for each HTTP request. Use a Go duration such as 30s, 2m, or 1h.
caCertFile	-	Path to a PEM-encoded CA certificate bundle used for API and authorization TLS connections.

Configuration precedence

For each supported setting, Nobl9 tools use the first available value in this order:

1. Tool options, command flags, provider arguments, or SDK configuration options.
2. Environment variables.
3. The selected context in config.toml.
4. The default value, when the setting has one.

An explicitly empty environment variable can select a built-in default instead of the file value. See Empty environment variables before clearing a variable.

Configuration precedence diagram

Context selection follows the same model. A tool-specific context option, such as sloctl --context, takes precedence over <PREFIX>DEFAULT_CONTEXT. The environment variable takes precedence over defaultContext in the file. If none is set, the context name is default.

Authentication flow

Nobl9 tools resolve configuration before they create an API client. The client first tries the access token stored in the selected context. If the token is unavailable, invalid, or near expiration, the client requests a new token with clientId and clientSecret. When file configuration is enabled, the client saves the new token in the selected context.

Authentication flow diagram

The token supplies the Nobl9 API host and organization.

Environment variables

The shared configuration fields use a tool-specific prefix and a common suffix. For example, CLIENT_ID becomes SLOCTL_CLIENT_ID in sloctl.

Tool prefixes

Tool	Prefix	Example
sloctl and tools that wrap it	SLOCTL_	SLOCTL_CLIENT_ID
Nobl9 SDK for Go	NOBL9_SDK_	NOBL9_SDK_CLIENT_ID
Nobl9 Terraform provider shared configuration	TERRAFORM_NOBL9_	TERRAFORM_NOBL9_CLIENT_ID

SDK users can select another prefix with sdk.ConfigOptionEnvPrefix.

Shared variable suffixes

Suffix	Configuration field	Description
CONFIG_FILE_PATH	Configuration path	Uses the specified config.toml file.
NO_CONFIG_FILE	File loading	Set to true to prevent configuration file reads and creation.
DEFAULT_CONTEXT	defaultContext	Selects the default context.
CLIENT_ID	clientId	Sets the client ID.
CLIENT_SECRET	clientSecret	Sets the client secret.
ACCESS_TOKEN	accessToken	Supplies an access token.
PROJECT	project	Sets the default Project.
OKTA_ORG_URL	oktaOrgURL	Sets the authorization service URL.
OKTA_AUTH_SERVER	oktaAuthServer	Sets the authorization server ID.
TIMEOUT	timeout	Sets the HTTP request timeout as a Go duration.
CA_CERT_FILE	caCertFile	Sets the CA certificate bundle path.

Empty environment variables

An unset environment variable allows the loader to use the file configuration. For the shared variables listed above, an explicitly empty variable behaves differently:

• If the variable supplies a nonempty default, the empty variable selects that default instead of the file value.
• Otherwise, the empty variable leaves the file value unchanged.

For example, SLOCTL_PROJECT="" selects the default Project, even if the selected file context specifies another Project. Empty SLOCTL_OKTA_ORG_URL or SLOCTL_OKTA_AUTH_SERVER variables select their EU defaults, not the US values in the file.

Unset the variables to inherit the file settings:

unset SLOCTL_PROJECT SLOCTL_OKTA_ORG_URL SLOCTL_OKTA_AUTH_SERVER

Terraform provider overrides

The Terraform provider also accepts provider arguments and NOBL9_* environment variables. Provider arguments have the highest precedence. The corresponding NOBL9_* variable supplies a default when an argument is absent.

Provider argument	Environment variable
client_id	NOBL9_CLIENT_ID
client_secret	NOBL9_CLIENT_SECRET
project	NOBL9_PROJECT
okta_org_url	NOBL9_OKTA_URL
okta_auth_server	NOBL9_OKTA_AUTH
no_config_file	NOBL9_NO_CONFIG_FILE

These values take precedence over the shared Terraform configuration and config.toml.

sloctl variables

Variable	Configuration field	Description
SLOCTL_EDITOR	None	Editor command used by sloctl edit. It takes precedence over EDITOR.
SLOCTL_ACCESSIBLE_MODE	None	Enables accessible interactive forms when set to true.
SLOCTL_FILES_PROMPT_ENABLED	sloctl.filesPromptEnabled	Enables or disables the sloctl file confirmation prompt.
SLOCTL_FILES_PROMPT_THRESHOLD	sloctl.filesPromptThreshold	Sets the sloctl file confirmation threshold.

Empty SLOCTL_FILES_PROMPT_ENABLED and SLOCTL_FILES_PROMPT_THRESHOLD variables leave the file values unchanged. Unlike the shared variables with nonempty defaults, they do not reset the file values to their defaults.

Security considerations

The configuration file can contain client secrets and access tokens. Do not commit it to source control or include real values in logs and support requests. Restrict file access to the user who runs the Nobl9 tool.

When possible, use your automation platform's secret store for environment variables. Use <PREFIX>NO_CONFIG_FILE=true when a temporary environment must not create or update config.toml.