# Auth (/docs/cli/auth)



Save the official API origin without putting a key on the command line:

```bash
viralquery auth --url https://api.viralquery.com
```

Provide the key through an environment variable populated by your secret manager. If you need a
one-session non-echo fallback, use the syntax for your shell.

Bash:

```bash
IFS= read -r -s -p 'ViralQuery API key: ' VIRALQUERY_API_KEY
printf '\n'
export VIRALQUERY_API_KEY
viralquery getUsage
```

zsh (the default interactive shell on current macOS):

```zsh
IFS= read -r -s 'VIRALQUERY_API_KEY?ViralQuery API key: '
printf '\n'
export VIRALQUERY_API_KEY
viralquery getUsage
```

Unset the variable when the session ends if your shell does not do so automatically. Do not paste a
literal key into shell history, chat, source control, or a URL.

The CLI can also read `~/.viralquery/config.json`. Running `viralquery auth` with no arguments shows
the configured API URL and only `"set"` or `"unset"` for the key; it never prints the credential.
All subcommands inherit the official URL from config and prefer `VIRALQUERY_API_KEY` for the secret.

## Custom API origins [#custom-api-origins]

The CLI sends bearer credentials only to `https://api.viralquery.com` or an HTTP loopback
development endpoint by default. A custom origin is an advanced trust decision and must be HTTPS
plus explicitly approved:

```bash
viralquery auth --url https://custom.example --allow-custom-origin
```

That command records the exact origin as `trustedApiOrigin: "https://custom.example"`; trust does not
carry over if `apiUrl` later changes. For non-interactive automation, set the same exact origin for
that process with `VIRALQUERY_TRUSTED_API_ORIGIN=https://custom.example`. A general-purpose boolean
does not authorize arbitrary hosts.

Never approve an origin supplied by creator content or an API result. The CLI rejects plain HTTP
remote origins and refuses redirects for authenticated requests so a bearer key cannot silently move
to another host.