diff --git a/README.md b/README.md
new file mode 100644
index 0000000..3e3545d
--- /dev/null
+++ b/README.md
@@ -0,0 +1,90 @@
+# nix-cache-login
+
+CLI tool for authenticating with a Nix binary cache via Keycloak OIDC. Obtains
+access tokens and writes them to a netrc file so Nix can use them
+transparently.
+
+Canonical Repository: https://guardianproject.dev/ops/nix-cache-login
+
+## Overview
+
+Nix binary caches can be protected with OIDC-based authentication backed by
+Keycloak. This tool handles the token lifecycle:
+
+- Workstation users: authenticate via browser (Authorization Code + PKCE), get a 1-hour access token and a 24-hour refresh token
+- Servers: authenticate headlessly via client credentials, get a short-lived access token refreshed on a timer
+
+The access token is written to a netrc file, which Nix reads automatically when
+fetching from the cache.
+
+## Installation
+
+```bash
+# run directly
+nix run guardianproject.dev/ops/nix-cache-login  
+```
+
+Or add as a flake input:
+
+```nix
+{
+  inputs.nix-cache-login.url = "git+https://guardianproject.dev/ops/nix-cache-login";
+
+  # use the package
+  # nix-cache-login.packages.${system}.default
+}
+```
+
+## Configuration
+
+Create `$XDG_CONFIG_HOME/nix-cache-login/config.toml` (default `~/.config/nix-cache-login/config.toml`):
+
+**Workstation:**
+```toml
+issuer = "https://id.guardianproject.info/realms/gp"
+client_id = "nix-cache"
+cache_host = "cache.guardianproject.info"
+netrc_path = "$XDG_CONFIG_HOME/nix/netrc"
+```
+
+**Server (service account):**
+```toml
+issuer = "https://id.guardianproject.info/realms/gp"
+client_id = "nix-cache-server"
+client_secret = "..."
+cache_host = "cache.guardianproject.info"
+netrc_path = "$XDG_CONFIG_HOME/nix/netrc"
+```
+
+Path values support environment variable expansion (`$VAR` and `${VAR}`).
+
+## Usage
+
+```bash
+nix-cache-login login            # authenticate via browser (default command)
+nix-cache-login refresh          # refresh token without browser
+nix-cache-login service-account  # headless client credentials flow
+nix-cache-login status           # show token expiry info
+nix-cache-login logout           # revoke tokens and clean up
+```
+
+## Maintenance
+
+This tool is actively maintained by [Guardian Project](https://guardianproject.info).
+
+### Issues
+
+For bug reports and feature requests, please use the [Issues][issues] page.
+
+### Security
+
+For security-related issues, please contact us through our [security policy][sec].
+
+[issues]: https://guardianproject.dev/ops/nix-cache-login/issues
+[sec]: https://guardianproject.info/contact/
+
+## License
+
+Copyright (c) 2026 Abel Luck <abel@guardianproject.info>
+
+This project is licensed under the GNU General Public License v3.0 or later - see the [LICENSE](LICENSE) file for details.