Configuration and authentication

snow-cli keeps connection metadata in a config file and stores secrets in the operating system keychain where possible.

Where configuration lives

By default, profiles are stored in:

~/.servicenow/config.toml

The config file contains non-secret settings such as:

  • instance URL,
  • authentication method,
  • username,
  • OAuth client ID and grant settings,
  • mTLS certificate paths (not yet implemented),
  • default profile name.

Secrets such as passwords, API tokens, OAuth client secrets, and stored OAuth tokens are kept outside the TOML file.

Profiles

Profiles describe how snow-cli connects to a ServiceNow instance.

Create a basic-auth profile:

snow-cli profile add dev \
  --instance https://dev.service-now.com \
  --auth-method basic \
  --username admin

List configured profiles:

snow-cli profile list

Set the default profile:

snow-cli profile default dev

Show which profile is active:

snow-cli profile current
snow-cli profile show

Use a specific profile for one command:

snow-cli --profile dev table list incident --limit 10

For detailed profile management, see profile.

Authentication commands

Once a profile exists, store or refresh credentials with:

snow-cli auth login
snow-cli auth status
snow-cli auth token
snow-cli auth logout

For detailed auth behavior and secret input options, see auth.

Supported authentication methods

The CLI supports these --auth-method values:

  • basic
  • oauth2
  • api-key
  • browser-session

In config.toml, the API key method is serialized as api_key.

Basic authentication

Store username in the profile and the password with auth login:

snow-cli profile add dev \
  --instance https://dev.service-now.com \
  --auth-method basic \
  --username admin

snow-cli auth login --profile dev

OAuth 2.0

snow-cli supports three OAuth2 grant types:

  • client-credentials
  • password
  • authorization-code

Use authorization-code when you need the CLI to act in user scope. That flow uses a browser login, a localhost callback, and PKCE.

See the dedicated guide:

API key

Create a profile and store the token:

snow-cli profile add integration \
  --instance https://dev.service-now.com \
  --auth-method api-key

printf '%s' "$SNOW_API_TOKEN" | snow-cli auth login --profile integration --token-stdin

Browser session

browser-session profiles accept an already-authenticated Cookie header value from your browser. This is useful for instances that require SSO or SAML, where you can copy the cookie from an authenticated browser session.

Example profile:

snow-cli profile add sso-dev \
  --instance https://dev.service-now.com \
  --auth-method browser-session

Then provide the cookie at runtime via the SNOW_SESSION_COOKIE environment variable or the --session-cookie flag:

export SNOW_SESSION_COOKIE='JSESSIONID=...; glide_user_route=...'
snow-cli table list incident --limit 10 --profile sso-dev

The session cookie is never stored in the config file or keychain.

Global options

Common top-level flags:

snow-cli --profile dev <command>
snow-cli --instance https://override.service-now.com <command>
snow-cli --output json|csv|jsonl|toon|text <command>
snow-cli --timeout-secs 30 <command>
snow-cli -v <command>
snow-cli -vv <command>

Discover more