CLI Configuration Concept

The Niksphere CLI (nik) supports the same flexible runtime configuration model as the Engine. Parameters can be supplied either via Configuration Files (config.yaml, config.json, or config.toml) or via Environment Variables (all prefixed with NIKSPHERE_CLI_).

Configuration Sources

• Configuration File — A single config.yaml, config.json, or config.toml file holding all settings as key/value pairs. Either passed explicitly via --config <path> (or -c <path>), or auto-discovered by the CLI — see Configuration File below.
• Environment Variables — Any configuration key can also be supplied as an environment variable using the NIKSPHERE_CLI_ prefix — see Environment Variables below.

Configuration File

If --config <path> / -c <path> is not provided, the CLI automatically searches for a file named config (with a .yaml, .json, or .toml extension) in the following locations, in order, and loads the first one it finds:

1. User config directory (OS-specific — one of three Standard Directories the CLI resolves, alongside State and Cache):
   • Windows: %APPDATA%\Niksphere\cli\
   • macOS: ~/Library/Application Support/Niksphere/cli/
   • Linux: $XDG_CONFIG_HOME/niksphere/cli/ (defaults to ~/.config/niksphere/cli/)
2. System-wide directory:
   • Windows: %PROGRAMDATA%\Niksphere\cli\
   • Linux / macOS: /etc/niksphere/cli/
3. The nik executable's own directory
4. The current working directory

Unlike the Engine (where --config only applies to the run/service commands), the CLI's --config/-c is a persistent flag available on every nik subcommand. Passing it skips the search above entirely and loads exactly the given file instead.

Example

Any one of the following (matched by file extension) works — place it in one of the locations above, e.g. ~/.config/niksphere/cli/config.yaml on Linux:

config.yaml

server: "http://localhost:3000"

config.json

{
  "server": "http://localhost:3000"
}

config.toml

server = "http://localhost:3000"

Environment Variables

Every configuration key can also be supplied as an environment variable. The CLI uppercases the key and prefixes it with NIKSPHERE_CLI_.

Example

$env:NIKSPHERE_CLI_SERVER="http://engine.company.internal:3000"
$env:NIKSPHERE_CLI_TOKEN="<personal-access-token>"

export NIKSPHERE_CLI_SERVER="http://engine.company.internal:3000"
export NIKSPHERE_CLI_TOKEN="<personal-access-token>"

export NIKSPHERE_CLI_SERVER="http://engine.company.internal:3000"
export NIKSPHERE_CLI_TOKEN="<personal-access-token>"

.env File

NIKSPHERE_CLI_SERVER=http://engine.company.internal:3000
NIKSPHERE_CLI_TOKEN=<personal-access-token>

Configuration Precedence

When the same setting is supplied through more than one source, the CLI resolves it in the following priority order (highest to lowest):

1. Command-Line Flags (--config <path>)
2. Environment Variables (NIKSPHERE_CLI_*)
3. Configuration File (config.yaml / config.json / config.toml)
4. Default Values

In practice, this means an environment variable overrides the same key set in a configuration file, and pointing --config at a different file changes which file is consulted in the first place.

Related Documentation

• CLI Reference — CLI commands, API specifications, and release notes for Niksphere CLI.
• CLI Installation & Setup Quickstart — Quickstart guide to installing and setting up the CLI.
• Engine Configuration Concept — The Engine follows the same configuration model.
• Standard Directories Concept — The Config directory above is one of three OS-standard directories (Config/State/Cache) the CLI resolves.