Standard Directories Concept

The Niksphere CLI and Niksphere Engine both resolve a small set of OS-standard directories for configuration, persistent state, and disposable cache data. This applies equally whether you're an administrator operating an Engine instance or a developer using the CLI day to day — knowing where these directories live helps you find configuration files, back up what matters, and safely clean up what doesn't.

Why Three Directories?

Rather than lumping everything into one folder, each component separates its on-disk data by lifetime and purpose:

• Config — settings deliberately provided by a human (or provisioning script). Meant to be backed up and versioned; never written to by the application itself.
• State — data the application generates and depends on across restarts, but that isn't meant to be hand-edited. Should survive upgrades and be included in backups.
• Cache — disposable, reproducible data. Safe to delete at any time — at worst, the application regenerates it or a debug feature has nothing to show until the next run.

This split follows the same idea as the XDG Base Directory Specification that most Linux tools follow, applied consistently across Windows, macOS, and Linux.

Directory Purposes

Directory	Purpose	CLI (nik)	Engine
Config	User-provided settings	config.yaml / .json / .toml — see CLI Configuration Concept	config.yaml / .json / .toml — see Engine Configuration Concept
State	Persistent runtime state	state.json (last active server URL, last active Cloud backend URL)	Embedded SQLite database file (niksphere.db), when db_driver is sqlite and db_name/db_url don't point elsewhere — see Engine Database Concept
Cache	Disposable/debug data	Reserved for future disposable data — not currently used	Bytecode debug export (bytecode.bin / bytecode.txt), written when debug_export_bytecode is enabled

Platform-Specific Paths

Both components resolve these directories the same way, only the component name in the path differs (Engine vs. cli) — note that on Linux/BSD the component name is always lowercased, while Windows and macOS keep the given case:

Engine

Config:
  Windows: %APPDATA%\Niksphere\Engine\
  macOS:   ~/Library/Application Support/Niksphere/Engine/
  Linux:   $XDG_CONFIG_HOME/niksphere/engine/  (default ~/.config/niksphere/engine/)

State:
  Windows: %LOCALAPPDATA%\Niksphere\Engine\
  macOS:   ~/Library/Caches/Niksphere/Engine/
  Linux:   $XDG_STATE_HOME/niksphere/engine/  (default ~/.local/state/niksphere/engine/)

Cache:
  Windows: %TEMP%\Niksphere\Engine\
  macOS:   $TMPDIR/Niksphere/Engine/
  Linux:   $XDG_CACHE_HOME/niksphere/engine/  (default ~/.cache/niksphere/engine/)

CLI

Config:
  Windows: %APPDATA%\Niksphere\cli\
  macOS:   ~/Library/Application Support/Niksphere/cli/
  Linux:   $XDG_CONFIG_HOME/niksphere/cli/  (default ~/.config/niksphere/cli/)

State:
  Windows: %LOCALAPPDATA%\Niksphere\cli\
  macOS:   ~/Library/Caches/Niksphere/cli/
  Linux:   $XDG_STATE_HOME/niksphere/cli/  (default ~/.local/state/niksphere/cli/)

Cache:
  Windows: %TEMP%\Niksphere\cli\
  macOS:   $TMPDIR/Niksphere/cli/
  Linux:   $XDG_CACHE_HOME/niksphere/cli/  (default ~/.cache/niksphere/cli/)

Startup Log Output

The Engine logs all three resolved paths every time it starts, right after loading its configuration — so you never need to look them up manually:

INF MAIN Config directory  path=C:\Users\<you>\AppData\Roaming\Niksphere\Engine
INF MAIN State directory   path=C:\Users\<you>\AppData\Local\Niksphere\Engine
INF MAIN Cache directory   path=C:\Users\<you>\AppData\Local\Temp\Niksphere\Engine

Related Documentation

• CLI Configuration Concept — Config file search order and environment variables for the CLI.
• Engine Configuration Concept — Config file search order and environment variables for the Engine.
• Engine Database Concept — Where the Engine's SQLite/PostgreSQL data actually lives, including how the SQLite file location relates to the State directory above.