> ## Documentation Index
> Fetch the complete documentation index at: https://docs.iriscode.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Authenticate the Iris Code CLI with Browser or Token

> Sign in to Iris Code CLI via browser OAuth for local development, or use IRIS_LICENCE_TOKEN for non-interactive CI runners. Credentials stored in ~/.iris/credentials.

How you authenticate depends on where the CLI is running.

**On your own machine**, run `iris auth login` and sign in through the browser.

**On a CI runner**, set `IRIS_LICENCE_TOKEN` as a secret instead. The CLI reads it directly, so there is no login step in the pipeline.

## The commands

`iris auth login` is interactive: it asks whether you want to sign in through the browser or paste a token. It requires a terminal, and reports an error rather than hanging when it does not have one.

```bash theme={null}
# Interactive sign-in (choose browser or token when prompted)
iris auth login

# Confirm active session
iris auth status

# Remove stored credentials
iris auth logout
```

## How credentials are stored

Both the browser flow and the manual token entry write to `~/.iris/credentials`. The file is created with `chmod 600` so only the current user can read it.

<Tip>
  Add `~/.iris/` to your global gitignore to prevent accidentally committing credentials to a repository.
</Tip>

## Priority order

The CLI resolves credentials in this order:

1. **`IRIS_LICENCE_TOKEN` environment variable** - checked first; takes precedence over the credentials file
2. **Credentials file at `~/.iris/credentials`** - written by `iris auth login`, whichever method (browser or manual token) you choose at the prompt

## Using IRIS\_LICENCE\_TOKEN in CI

The environment variable is the recommended approach for CI runners. It avoids writing any files to the runner filesystem and is revoked simply by rotating the secret in your repository settings.

```bash theme={null}
# Set for current shell session
export IRIS_LICENCE_TOKEN=sk_live_your_licence_key_here

# Or inline for a single command
IRIS_LICENCE_TOKEN=sk_live_your_licence_key_here iris gate
```

To use the token in a CI pipeline:

1. Add your licence key as a repository secret named `IRIS_LICENCE_TOKEN` in your CI provider settings.
2. Reference the secret as the `IRIS_LICENCE_TOKEN` environment variable in the workflow step that runs Iris Code.
3. The CLI reads the env var automatically - no `iris auth login` step is required on the runner.

<Note>
  `iris secrets` and `iris security` run without any authentication at all - both are free and require no licence. You can use either in any pipeline without setting `IRIS_LICENCE_TOKEN`.
</Note>