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

# Authentication and push

> Use connect for the guided hosted path, push explicit audit summaries when you want to, and keep local auditing separate from hosted workspace features.

Use `connect` when you want the guided hosted path after the first local audit. Use `audit --push` or `xerg push` when you want explicit push behavior.

> Local audits and compare are free with no account. Pushing works with a free workspace, which keeps the last 30 days of pushed audits and up to 100 stored snapshots per month. Ask Xerg, hosted MCP, Slack, and policies require a Pro or Enterprise workspace.

## Recommended hosted flow

After your first local audit:

```bash theme={null}
npx @xerg/cli@latest connect
```

`connect`:

* reuses auth from `XERG_API_KEY`, `~/.xerg/config.json`, or stored browser credentials when available
* prompts before browser login when auth is missing
* offers to push the latest cached audit, or the in-memory audit when called from `init`
* stays non-interactive when auth is already configured and no prompt is needed
* sends pushed audits to the workspace shown in the hosted dashboard

You can skip it and keep using Xerg locally.

## Explicit push flows

Push immediately after computing an audit:

```bash theme={null}
npx @xerg/cli@latest audit --push
```

Preview the exact payload without sending it:

```bash theme={null}
npx @xerg/cli@latest audit --push --dry-run
```

`audit --push --dry-run` prints the push payload to stdout and suppresses the normal audit report.

## Re-push a cached audit later

Push the most recent cached local snapshot:

```bash theme={null}
npx @xerg/cli@latest push
```

Preview it:

```bash theme={null}
npx @xerg/cli@latest push --dry-run
```

Push a specific saved payload file:

```bash theme={null}
npx @xerg/cli@latest push --file ./audit-payload.json
```

`xerg push --file` expects a JSON file that already matches the `AuditPushPayload` wire shape. It does not read an arbitrary local audit summary.

## Authentication precedence

Xerg resolves API credentials in this order:

1. `XERG_API_KEY`
2. `~/.xerg/config.json`
3. stored browser credentials from `xerg login`

Optional API URL overrides:

* `XERG_API_URL`
* `apiUrl` in `~/.xerg/config.json`

Example config:

```json theme={null}
{
  "apiKey": "sk_live_or_test_key",
  "apiUrl": "https://api.xerg.ai"
}
```

Create or rotate workspace API keys from the hosted dashboard Overview or Settings pages. The same workspace API key can be used for hosted MCP access. See [hosted dashboard](/docs/hosted-dashboard) and [hosted MCP](/docs/hosted-mcp) for setup details.

## Browser login

Start browser auth directly when you want stored credentials without the hosted push prompt:

```bash theme={null}
npx @xerg/cli@latest login
```

By default:

* Xerg opens the hosted dashboard settings page in your browser
* you create or copy a workspace API key there and paste it into the terminal
* the terminal prompt masks typed and pasted key characters
* Xerg verifies the key against `https://api.xerg.ai` and stores it at `~/.config/xerg/credentials.json`

The signup-first wizard uses this secure login flow by default. Its optional one-command path places `XERG_API_KEY=<key>` inline with the audit command; that can save the key in shell history and expose it to other processes running as your user. Rotate an exposed key in Workspace Settings.

If this machine already stores credentials for another workspace, use the wizard's replacement command:

```bash theme={null}
npx @xerg/cli@latest login --replace
```

Xerg verifies the new key before atomically replacing the existing credential, so a rejected key does not log you out of the current workspace.

At the Free limit of 100 distinct stored snapshots in a UTC month, new distinct pushes return a structured quota remedy with the reset time and Pro URL. Identical retries remain safe because they are deduplicated before quota accounting.

To clear stored browser credentials:

```bash theme={null}
npx @xerg/cli@latest logout
```

## What gets pushed

The push payload contains:

* a versioned audit summary
* daily spend and confirmed waste rollups
* top-level findings and taxonomy buckets
* ranked recommendations with where-to-change and validation guidance
* optional comparison deltas
* metadata such as CLI version, source ID, source host, environment, and push timestamp

The push payload does not include raw prompt or response content. It also omits local-only `sourceFiles` and `dbPath` fields from the audit summary.

## Push versus hosted MCP

Use push when you want to send audit summaries from the CLI into your hosted workspace.

Use hosted MCP when you want a remote MCP client to read hosted audit history, trends, recommendations, or selected hosted control actions from that workspace.

A common sequence is:

1. run `xerg init` or `xerg audit`
2. run `xerg connect`
3. verify the hosted audit in the [dashboard](/docs/hosted-dashboard)
4. review Optimizations or create a workspace API key in Settings
5. run `xerg mcp-setup` or connect a remote client to [hosted MCP](/docs/hosted-mcp)

## Important gotchas

* `xerg push` reads from the default local snapshot store path. It does not accept `--db`.
* If you used `xerg audit --db /custom/path`, push immediately with `xerg audit --push`, or export the payload and use `xerg push --file`.
* `--dry-run` on `xerg audit` requires `--push`.
* If hosted MCP returns empty audit results, push an audit first so the workspace has hosted data to query.
* If you authenticated with a stored browser login and hosted MCP still needs a workspace API key, create one in the dashboard and set `XERG_API_KEY`.