Contexts

A context is a named profile. It holds the address of a Nuvelics API and, kept in the keychain, the credential you signed in with. A credential belongs to one organization, so in practice a context is how you say which organization a command acts on. If you belong to several organizations, you keep one context for each.

One context is active at a time. Every command uses the active context unless you name another with --context.

What you start withCopy Anchor Link

The first time the tool runs on a machine with no contexts, it creates two: prod, which points at https://api.nuvelics.com/api and is active, and dev, which points at a local development API on your own machine. It prints a one-line notice when it does. Most integrators only ever use prod. Names carry no meaning to the tool; prod is only a label.

Add a contextCopy Anchor Link

nuvelics context add acme --api-url https://api.nuvelics.com/api

Adding a name that already exists overwrites it. A new context has no credential until you sign in to it:

nuvelics login --context acme

The context must exist before you sign in; login stores a credential and never creates a context.

List, switch and removeCopy Anchor Link

nuvelics context list
nuvelics context current
nuvelics context use acme
nuvelics context remove acme

• context list shows every context and marks the active one with *.
• context current prints the name of the active one.
• context use makes another context active. It changes the address and the credential together, with no new sign-in, as long as that context already has a credential.
• context remove deletes the context and its stored credential. If it was the active one, no context is active afterwards until you run context use.

Use another context for one commandCopy Anchor Link

nuvelics datasource list --context acme

--context applies to that one command and leaves the active context as it was. It works before or after the command name.

Name the context on every writeCopy Anchor Link

Commands that change something (create, approve, push, delete) must name their context when they run without a person at a keyboard, that is, when input is not a terminal, as in a script, a scheduled job or an agent:

nuvelics pitch approve <id> --context acme

Without --context the tool refuses, before sending anything, with the error kind ambiguous-context and the list of available contexts. This is deliberate: an unattended write should never act on whichever organization happened to be active when the job started. Reads are not affected, so nuvelics pitch list | jq ... works without --context. A write you type yourself at a terminal does not need it either.

If the context also has no credential, you get unauthenticated instead, because a missing credential is the more basic problem. login is exempt, since its job is to give a context its first credential.

Choose the name from nuvelics whoami, or from the context the person who set the job up named. See Scripts and agents.

The command reference for these commands is nuvelics context.