#############
Settings File
#############

File Name and Location
======================

Per-user
--------

``settings.ini`` is the file that contains settings for an individual's NSCLI installation, like SSO username and
preferred region. To find the exact location of the settings file, one can run ``nscli --version``. It will normally 
be located here:

:Mac OS X:    ``~/Library/Application Support/nscli/``
:Unix:        ``~/.config/nscli/`` or in ``$XDG_CONFIG_HOME``, if defined

.. :Windows:     ``C:\Users\<username>\AppData\Roaming\Rackspace\nscli\``

Per-environment
---------------

Optionally, ``settings.ini`` may also exist inside NSCLI's virtual environment. If it does, any settings there will 
override settings found in the per-user config file. NSCLI will read from this file, but not write to it. Location:
``<sys.prefix>/.config/nscli/``

File Format
===========

The file uses the ``ini`` format, which is an informal format that is popular for this sort of usage. It is laid out in
sections, where each section begins with a title enclosed in brackets, and continues with a list of ``key = value``
entries, one line at a time. Internally, NSCLI uses the ``configparser`` module of the Python standard library to 
interact with this file. 

Modifying Settings
==================

Since the settings file is just a plain-text file in ``ini`` format, it can be edited with any standard text editor; 
no programming knowledge is needed. Also, the ``nscli settings`` command provides a shortcut to accessing this file,
and will attempt to open it in the user's preferred text editor. To help ``nscli settings`` work as intended, make sure
that the operating system has a program configured to open ``.ini`` files, or that the ``$EDITOR`` environment variable 
is properly set and exported.

Restoring Defaults
==================

If the settings file is deleted, NSCLI will replace it with a default version the next time it is needed. 
``nscli reset`` does not delete the settings file. ``nscli upgrade`` does not delete the settings file unless it is 
necessary to complete the upgrade.
