Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@
- Dependencies: refresh the Google API client, golangci-lint, Cloudflare Workers types, Wrangler, PostCSS, and Undici while retaining Go 1.26, pnpm 11, and the worker’s 24-hour release cooldown.
- Drive: preserve requested top-level false booleans in `drive get --json`, including the default `starred` and `hasThumbnail` fields; keep conditionally absent fields omitted. (#1223) — thanks @postoso.
- CI: use macOS 27 runners for Darwin checks and release preflight while enforcing the macOS 15.0 deployment target.
- Auth: add `gog auth rekey <outdir>` to write and verify a separate re-encrypted directory while leaving the live keyring untouched; hold the store lock throughout, publish only complete fsynced output, and retain the old directory during installation. (#1224) — thanks @sorenisanerd.
- Dependencies: update Vitest and Cloudflare Workers types within the worker’s 24-hour release cooldown.
- Google APIs: add `GOG_GOOGLE_API_BASE_URL` to send `*.googleapis.com` requests to a test server, emulator, proxy, or relay that adds credentials outside gog; requests keep path and query, pass the original host as `X-Forwarded-Host`, carry no gog credentials, and refuse cross-origin redirects. (#1225, #1226) — thanks @km-tr.
- Gmail: add `--note-html` and `--note-html-file` to forwards and preserve plain-note line breaks in HTML output. (#1215) — thanks @malob.
Expand Down
1 change: 1 addition & 0 deletions docs/commands.generated.md
Original file line number Diff line number Diff line change
Expand Up @@ -90,6 +90,7 @@ Generated from `gog schema --json`.
- [`gog auth keyring [<backend> [<backend2>]]`](commands/gog-auth-keyring.md) - Configure keyring backend
- [`gog auth list [flags]`](commands/gog-auth-list.md) - List stored accounts
- [`gog auth manage (login) [flags]`](commands/gog-auth-manage.md) - Open interactive accounts manager in browser
- [`gog auth rekey <outdir> [flags]`](commands/gog-auth-rekey.md) - Write a verified copy of the file keyring to <outdir> using GOG_KEYRING_NEW_PASSWORD; leave the live keyring untouched
- [`gog auth remove <email>`](commands/gog-auth-remove.md) - Remove a stored refresh token
- [`gog auth service-account <command>`](commands/gog-auth-service-account.md) - Configure service account (Workspace only; domain-wide delegation)
- [`gog auth service-account set <email> [flags]`](commands/gog-auth-service-account-set.md) - Store a service account key for impersonation
Expand Down
3 changes: 2 additions & 1 deletion docs/commands/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

Every `gog` command has a generated docs page. The source of truth is the live CLI schema; run `make docs-commands` after changing command names, flags, help text, aliases, or arguments.

Generated pages: 779.
Generated pages: 780.

## Top-level Commands

Expand Down Expand Up @@ -144,6 +144,7 @@ Generated pages: 779.
- [gog auth keyring](gog-auth-keyring.md) - Configure keyring backend
- [gog auth list](gog-auth-list.md) - List stored accounts
- [gog auth manage](gog-auth-manage.md) - Open interactive accounts manager in browser
- [gog auth rekey](gog-auth-rekey.md) - Write a verified copy of the file keyring to <outdir> using GOG_KEYRING_NEW_PASSWORD; leave the live keyring untouched
- [gog auth remove](gog-auth-remove.md) - Remove a stored refresh token
- [gog auth service-account](gog-auth-service-account.md) - Configure service account (Workspace only; domain-wide delegation)
- [gog auth service-account set](gog-auth-service-account-set.md) - Store a service account key for impersonation
Expand Down
48 changes: 48 additions & 0 deletions docs/commands/gog-auth-rekey.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
# `gog auth rekey`

> Generated from `gog schema --json`. Do not edit this page by hand; run `make docs-commands`.

Write a verified copy of the file keyring to <outdir> using GOG_KEYRING_NEW_PASSWORD; leave the live keyring untouched

## Usage

```bash
gog auth rekey <outdir> [flags]
```

## Parent

- [gog auth](gog-auth.md)

## Flags

| Flag | Type | Default | Help |
| --- | --- | --- | --- |
| `--access-token` | `string` | | Use provided access token directly (bypasses stored refresh tokens; token expires in ~1h) |
| `-a`<br>`--account`<br>`--acct` | `string` | | Account email, alias, or auto for authenticated Google API commands |
| `--client` | `string` | | OAuth client name (selects stored credentials + token bucket) |
| `--color` | `string` | auto | Color output: auto\|always\|never |
| `--disable-commands` | `string` | | Comma-separated list of disabled commands; dot paths allowed |
| `-n`<br>`--dry-run`<br>`--dryrun`<br>`--noop`<br>`--preview` | `bool` | | Do not make changes; print intended actions and exit successfully |
| `--enable-commands` | `string` | | Comma-separated list of enabled command prefixes; dot paths allowed (restricts CLI) |
| `--enable-commands-exact` | `string` | | Comma-separated list of exact enabled commands; dot paths allowed and parent commands do not enable children |
| `-y`<br>`--force`<br>`--assume-yes`<br>`--yes` | `bool` | | Skip confirmations for destructive commands |
| `--gmail-no-send` | `bool` | false | Block Gmail send operations (agent safety) |
| `-h`<br>`--help` | `kong.helpFlag` | | Show context-sensitive help. |
| `--home` | `string` | | Override gogcli config/data/state/cache root (equivalent to GOG_HOME) |
| `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
| `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` | | Never prompt; fail instead (useful for CI) |
| `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
| `--quota-project` | `string` | | Google Cloud project to bill for API usage (sent as X-Goog-User-Project; some APIs require it with --access-token or ADC) |
| `--readonly` | `bool` | false | Block mutating API requests at runtime; auth add also requests read-only OAuth scopes |
| `--results-only` | `bool` | | In JSON mode, emit only the primary result (drops envelope fields like nextPageToken) |
| `--select`<br>`--pick`<br>`--project` | `string` | | In JSON mode, select comma-separated fields (best-effort; supports dot paths). Desire path: use --fields for most commands. |
| `--skip-unreadable` | `bool` | | Omit undecryptable items from output and report their keys; live items remain untouched |
| `-v`<br>`--verbose` | `bool` | | Enable verbose logging |
| `--version` | `kong.VersionFlag` | | Print version and exit |
| `--wrap-untrusted` | `bool` | false | In JSON/raw output, wrap fetched text fields in external untrusted-content markers |

## See Also

- [gog auth](gog-auth.md)
- [Command index](README.md)
1 change: 1 addition & 0 deletions docs/commands/gog-auth.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@ gog auth <command> [flags]
- [gog auth keyring](gog-auth-keyring.md) - Configure keyring backend
- [gog auth list](gog-auth-list.md) - List stored accounts
- [gog auth manage](gog-auth-manage.md) - Open interactive accounts manager in browser
- [gog auth rekey](gog-auth-rekey.md) - Write a verified copy of the file keyring to <outdir> using GOG_KEYRING_NEW_PASSWORD; leave the live keyring untouched
- [gog auth remove](gog-auth-remove.md) - Remove a stored refresh token
- [gog auth service-account](gog-auth-service-account.md) - Configure service account (Workspace only; domain-wide delegation)
- [gog auth services](gog-auth-services.md) - List supported auth services and scopes
Expand Down
2 changes: 1 addition & 1 deletion docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@ live binary.
- **Serving MCP tools.** [MCP server](mcp.md) exposes typed, allowlisted tools for agent clients without a generic command bridge.
- **Discovering runtime contracts.** [Automation](automation.md) explains root help, schema metadata, safety controls, and stable exit codes.
- **Polling local events.** [Drive and Docs polling](polling.md) persists cursors and optionally invokes trusted shell hooks.
- **Persisting auth and state.** [Paths and State](paths.md) covers `GOG_HOME`, per-kind directories, XDG paths, and legacy compatibility.
- **Persisting auth and state.** [Paths and State](paths.md) covers `GOG_HOME`, per-kind directories, XDG paths, legacy compatibility, and rotating the file keyring password without re-authorizing accounts.
- **Running Workspace at scale.** [Auth Clients](auth-clients.md) for service accounts, named OAuth clients, and domain-wide delegation.
- **Managing Workspace.** [Workspace Admin](workspace-admin.md) covers user creation, cleanup, organizational units, and group administration.
- **Backing up an account.** [Backup](backup.md) before pointing `gog backup push` at a busy mailbox.
Expand Down
71 changes: 71 additions & 0 deletions docs/paths.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,77 @@ Existing installs are read-compatible:
New writes use the new path for the selected kind. `auth credentials remove`
and service-account removal clean up both new and legacy locations where safe.

## Changing the Keyring Password

`gog auth rekey <outdir>` reads the file keyring with the current password and
writes a verified copy encrypted with the new password to the separate output
directory given as its argument:

```bash
GOG_KEYRING_PASSWORD='current password' \
GOG_KEYRING_NEW_PASSWORD='new password' \
gog auth rekey /path/to/new-keyring
```

Credential files are read-only: their contents, permissions and password remain
untouched on success, failure or interruption. Rekey holds the shared store lock
through reading, writing, verification and publication, blocking credential writes
until it finishes. It may create the normal `.lock` bookkeeping file. Rekey never
installs the output into the live keyring.

The output directory receives the source directory's permissions. It must be
outside the live directory and cannot be that directory or one of its ancestors,
including aliases through symlinks. Existing empty output is accepted. Nonempty
output is refused unless you explicitly pass `--force`, which replaces the whole
output directory and reports the names replaced; it never merges files. It writes
into a private sibling directory, verifies every entry, flushes ciphertext files
and directory metadata, then atomically exchanges the complete directories on
Linux and macOS. A write or verification failure leaves previous output intact;
a publication sync failure rolls back. If rollback also fails, the error identifies
the retained previous output for recovery. Interruption can leave a hidden
`.gog-rekey-*` sibling; inspect it before removing it. On filesystems without atomic
directory exchange, and on Windows, choose a fresh output path: existing output is
refused unchanged. Windows flushes ciphertext files but cannot fsync directories.

Before reporting success, rekey independently opens the output with the new
password and reads every item back, comparing its data and metadata. Output
contains only this run's entries: no password verifier or internal lock file is
created. An empty keyring produces empty output and explicitly reports that no
password was changed or established.

Inspect the output and any reported unreadable keys before installing it. The
command prints the exact move command for your paths (a shell command on Linux
and macOS, a PowerShell command on Windows). Stop running `gog` processes before
moving directories so their subsequent writes are not lost. For example:

```bash
test ! -e '/path/to/keyring.old' && test ! -L '/path/to/keyring.old' && mv -- '/path/to/keyring' '/path/to/keyring.old' && mv -- '/path/to/new-keyring' '/path/to/keyring'
```

Keep the old directory until the new keyring is proven. After installing the
output, update `GOG_KEYRING_PASSWORD` in the shell, services and CI that use it,
and test your normal commands. The command refuses to overwrite an existing
`.old` directory. These installation steps are the user's action, separate from
rekey.

Passwords come from the environment or a no-echo TTY prompt, never from argv.
The interactive new-password prompt asks twice and preserves whitespace.
Paths, counts and key names can appear in output; payloads and passwords cannot.

- Undecryptable entries abort before output is replaced. With
`--skip-unreadable`, they are omitted from output and their keys are reported;
their live copies remain untouched. A password that opens no entry is always
an error, even with this flag. Inspect omissions before installing the output.
- Only the file backend qualifies. `auto` qualifies on headless Linux without a
D-Bus session, where `gog` forces the file backend. Other `auto` configurations
are refused without opening an OS keychain or creating a live directory; use
`gog auth keyring file` if the file backend is your intended store.
- Legacy filenames are read without modification and written encoded in the
output. Conflicting legacy and encoded copies of a key abort rather than
silently discarding one.
- The lock gives rekey a consistent snapshot. Credentials can change after it
releases the lock, so stop other `gog` processes before installing the output.

## Containers and Agents

For a single persistent root:
Expand Down
1 change: 1 addition & 0 deletions internal/cmd/auth.go
Original file line number Diff line number Diff line change
Expand Up @@ -118,6 +118,7 @@ type AuthCmd struct {
Aliases AuthAliasCmd `cmd:"" name:"alias" help:"Manage account aliases"`
Status AuthStatusCmd `cmd:"" name:"status" help:"Show auth configuration and keyring backend"`
Keyring AuthKeyringCmd `cmd:"" name:"keyring" help:"Configure keyring backend"`
Rekey AuthRekeyCmd `cmd:"" name:"rekey" help:"Write a verified copy of the file keyring to <outdir> using GOG_KEYRING_NEW_PASSWORD; leave the live keyring untouched"`
Remove AuthRemoveCmd `cmd:"" name:"remove" help:"Remove a stored refresh token"`
Tokens AuthTokensCmd `cmd:"" name:"tokens" help:"Manage stored refresh tokens"`
Manage AuthManageCmd `cmd:"" name:"manage" help:"Open interactive accounts manager in browser" aliases:"login"`
Expand Down
Loading
Loading