Skip to content

OS keyring storage

nsc can keep a profile's API token in your operating system's keyring (macOS Keychain, Secret Service / libsecret on Linux, Windows Credential Manager) instead of in ~/.nsc/config.yaml. The config file then holds only a !keyring NAME reference — the counterpart of the !env NAME indirection.

profiles:
  prod:
    url: https://netbox.example.com
    token: !keyring prod

Storing a token

nsc login writes the token to the keyring and the reference to the config in one step. The token is prompted with hidden input, verified against NetBox first, and never written to disk in plaintext.

nsc login --new --profile prod --url https://netbox.example.com --store keyring
nsc login --new --profile prod --url https://netbox.example.com \
  --store keyring --keyring-name my-token          # choose the entry name
nsc login --rotate --profile prod --store keyring  # move an existing profile into the keyring
Option Default
--store keyring --new: plaintext unless given. --rotate: keyring if the profile already uses !keyring, otherwise plaintext.
--keyring-name NAME The existing !keyring name on --rotate, otherwise the profile name.

Rotating a profile that already uses !keyring updates the keyring entry in place, and the config file is left as it is.

How entries are named

Every entry uses the service name nsc, and the NAME from the tag is the keyring username. !keyring prod therefore maps to (service="nsc", username="prod"). To inspect or seed an entry by hand, use the keyring CLI that ships with the dependency:

keyring get nsc prod
keyring set nsc prod          # prompts for the secret
keyring del nsc prod

With the entry seeded this way, you can also write token: !keyring prod into the config yourself (nsc config edit).

When the keyring is read

!keyring references are kept unresolved when the config is loaded, but almost every invocation reads the keyring: to build the dynamic command tree, nsc needs the token to fetch the schema. That includes bare nsc, nsc --help, API requests, the static aliases (ls, get, rm, search), nsc login, and the live-hash check in nsc cache prune. On macOS, the first of these may show a Keychain access prompt.

Only shell completion and the meta commands nsc config, nsc profiles, nsc cache (except the prune live-hash check), nsc init, nsc commands, and nsc skill skip the keyring, so an unavailable keyring does not break them. --help on a static command such as nsc ls --help still prints usage when the keyring entry is missing.

The usual override order still applies: --token and NSC_TOKEN take priority, and when either is set the keyring is never read.

Errors

A missing entry or a missing keyring backend produces a config error envelope (exit code 12) rather than a traceback. The envelope's details.keyring_name names the entry (abridged):

{"error": "no OS keyring entry 'prod' (service 'nsc') for profile 'prod'; store one with `nsc login --rotate --profile prod --store keyring`.", "type": "config", "details": {"keyring_name": "prod"}}

Headless machines such as CI runners, containers, and SSH sessions without a desktop session often have no usable backend. Use !env indirection there, or install a backend such as keyrings.alt into the same environment as nsc. You can force a backend with the standard PYTHON_KEYRING_BACKEND environment variable.