> For the complete documentation index, see [llms.txt](https://wiki.crosswatch.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.crosswatch.app/crosswatch/settings/ui-settings/security/reset-administrator-access.md).

# Reset administrator access

Recover local administrator access with the CLI or a one-time Docker environment variable.

Use these recovery methods when you cannot sign in as the administrator.

### Reset the password with the CLI

Use the local CLI when you can access the host or container.

From the Docker host, run:

```bash
docker exec -it crosswatch cw --local auth setup --username admin --no-token
```

From inside the CrossWatch container, run:

```bash
cw --local auth setup --username admin --no-token
```

CrossWatch prompts for a new password and confirmation.

This method:

* Replaces the administrator password.
* Clears active web sessions.
* Preserves all other CrossWatch configuration and data.

Use this method when only the password needs replacement.

### Reset authentication with an environment variable

For Docker or Unraid installations, set the one-time recovery variable (see below, pick one)

```yaml
environment:
  CW_RESET_AUTH_ONCE: "true"
```

```yaml
environment:
    CW_RESET_AUTH_ONCE=1
```

Restart the CrossWatch container.

During startup, the application resets administrator authentication. The log includes:

```
[BOOT] CW_RESET_AUTH_ONCE detected: app authentication was reset.
Remove the env var and set a new username/password in the UI.
```

Then:

1. Open the CrossWatch web interface.
2. Configure a new administrator username and password.
3. Remove `CW_RESET_AUTH_ONCE` from Docker or Unraid.
4. Restart CrossWatch again.

{% hint style="warning" %}
Remove `CW_RESET_AUTH_ONCE` after recovery. Otherwise, a later restart resets authentication again.
{% endhint %}

This method resets:

* Administrator username and password.
* Active sessions and API tokens.
* Last login state.

It does not perform a factory reset. Providers, sync pairs, profiles, databases, and other configuration remain intact.

### Choose a method

Use the CLI when you forgot the password and have shell access.

Use `CW_RESET_AUTH_ONCE` to reset the full administrator authentication state. Then configure credentials through the web interface.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://wiki.crosswatch.app/crosswatch/settings/ui-settings/security/reset-administrator-access.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.