Sign in

A person signs the tool in. The tool never signs itself in, and it reads no credential from environment variables. Signing in needs a context to exist first; a fresh install already has one named prod, so most people can start right away.

Sign in with your browserCopy Anchor Link

nuvelics login

The tool opens your browser and also prints the address and a short code, in case the browser does not open or you are on another machine:

Contacting https://api.nuvelics.com/api...
Opening browser...
  https://app.nuvelics.com/oauth/activate?code=HJKL-MNPR

Or go to https://app.nuvelics.com/oauth/activate and enter: HJKL-MNPR

Waiting for authorization...

In the browser, check the code, choose the organization to authorize and confirm. The steps are on Activate a device sign-in. The tool then stores the credential and prints Logged in. API key stored in system keychain.

A credential obtained this way renews itself while you use the tool. If you wait too long, the code expires and the tool tells you that the device authorization expired and to run nuvelics login again. Do that.

To sign in a context other than the active one, name it explicitly. The context must be one you have added:

nuvelics login --context acme

Sign in with an API key you already haveCopy Anchor Link

An API key, created on the API keys tab, can be passed to the tool instead of using the browser:

nuvelics login --manual

The tool asks for the key with a hidden prompt, so it does not appear on screen. To supply it from a script or a secrets manager, pipe it in with --secret-stdin, which works only together with --manual:

printf '%s' "$NUVELICS_KEY" | nuvelics login --manual --secret-stdin

A pasted key is stored as it is and does not renew. It works until it is revoked or expires.

Keys are never accepted as a command-line value, because values on the command line show up in process lists and shell history. If you run login --manual without a terminal and without --secret-stdin, the tool stops and tells you to use --secret-stdin.

Check that it workedCopy Anchor Link

nuvelics whoami

whoami prints the active context, the address it talks to, the organization, and who you are signed in as:

context:      prod
endpoint:     https://api.nuvelics.com/api
organization: Example News (01K...)
user:         reporter@example.com (A. Reporter)
user id:      ...

A service key has no person behind it, so the user line reads (service key - no user).

whoami is also the readiness check for scripts. It confirms the credential before anything else runs, and if the tool is not signed in it fails at once, without contacting the API. See Scripts and agents.

Sign outCopy Anchor Link

nuvelics logout
nuvelics logout --context prod

This removes the stored credential for that context from the keychain. The context itself stays, so you can run nuvelics login again without adding it back.

Where the credential is keptCopy Anchor Link

Only in the operating system keychain, keyed by the context name, so each context has its own credential. The tool writes no credential to disk. The small file that holds your contexts, at ~/.config/nuvelics/cli/config.json (or under XDG_CONFIG_HOME if you set it), has the context names and addresses only, and is readable by you alone.

If the keychain is unavailable when you sign in, the tool stops with an error and stores nothing.