> For the complete documentation index, see [llms.txt](https://docs.nullify.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nullify.ai/cli/cli/authentication.md).

# Authentication

## Interactive Login

For interactive usage, the CLI opens your browser to authenticate directly with your identity provider:

```bash
nullify auth login --host api.<TENANT>.nullify.ai
```

This will:

1. Open your browser to authenticate with your identity provider (GitHub, Azure, Okta, etc.)
2. Redirect back to the CLI automatically once authenticated
3. Store the host in `~/.nullify/config.json` and the tokens in `~/.nullify/credentials.json`

## Auth Commands

### Check login status

```bash
nullify auth status
```

### View current token

```bash
nullify auth token
```

### Switch between hosts

```bash
nullify auth switch --host api.<OTHER-TENANT>.nullify.ai
```

### Log out

```bash
nullify auth logout
```

### View configuration

```bash
nullify auth config
```

## CI/CD Usage

For non-interactive environments (CI/CD pipelines, scripts), use token-based authentication:

### Using a Nullify API Token

```bash
nullify --nullify-token <TOKEN> findings --type sast
```

Or set via environment variable:

```bash
export NULLIFY_TOKEN=<TOKEN>
nullify findings --type sast
```

### Using a GitHub Token

Inside a GitHub Actions workflow, pass the workflow's GitHub token with `--github-token`. The CLI exchanges it for a Nullify token:

```bash
nullify --github-token ${{ secrets.GITHUB_TOKEN }} findings --type sast
```

{% hint style="info" %}
The GitHub token exchange only triggers when the CLI is running inside GitHub Actions — specifically when `GITHUB_ACTIONS=true` **and** `GITHUB_REPOSITORY` is set (both are provided automatically by the Actions runner). The token value itself must be supplied via the `--github-token` flag. The CLI does not independently read a bare `GITHUB_TOKEN` environment variable as a credential source.
{% endhint %}

## Token Precedence

The CLI resolves authentication in this order:

1. `--nullify-token` flag
2. `NULLIFY_TOKEN` environment variable
3. `--github-token` flag, exchanged for a Nullify token — only when `GITHUB_ACTIONS=true` and `GITHUB_REPOSITORY` is set
4. Stored credentials from `nullify auth login`

## Credential Storage

`nullify auth login` writes two files under `~/.nullify/`:

* **`config.json`** — stores the host you logged in to (`{"host": "..."}`), used to resolve the default Nullify instance for subsequent commands.
* **`credentials.json`** — a per-host map of credentials (keyed by host), each entry containing `access_token`, `refresh_token`, `expires_at`, and any `query_parameters` returned at login. Written with file permissions `0600` (owner read/write only).

Tokens are automatically refreshed using the stored refresh token when they expire.