Problem
The vibepaper sync feature (#2) requires an OAuth client secret at .vibepaper/credentials.json, but the docs do not explain how to create one. The README and CHANGELOG both say only:
Requires .vibepaper/credentials.json (OAuth client secret from Google Cloud Console).
For anyone who has not set up a Google Cloud OAuth client before, that one line leaves out every step that actually matters, and several of the steps are easy to get wrong in ways that fail late (only when you run sync and hit the browser flow).
What is non-obvious
While setting this up for a real project I hit or had to reason through the following, none of which is documented:
-
Which API to enable. Only the Google Docs API is needed (the code requests the single scope https://www.googleapis.com/auth/documents). Drive API is not required. Without enabling Docs API the first batchUpdate fails.
-
The OAuth client must be type "Desktop app". The auth code uses InstalledAppFlow.from_client_secrets_file(...).run_local_server(port=0). A "Web application" client secret will not work with this flow. This is the single most likely thing to get wrong, and the resulting file looks superficially fine. (You can tell them apart: a Desktop secret has a top-level "installed" key, a Web one has "web".)
-
The consent screen needs the user added as a test user. With an unpublished "External" app, authorization is rejected unless the authorizing account is listed under Test users. Publishing/verification is not required for personal use, but the test-user step is.
-
The first run is interactive and shows an "unverified app" warning. run_local_server opens a browser; because the app stays in Testing you get the "Google hasn't verified this app" screen and have to click Advanced then proceed. Worth saying so people do not assume something is broken. It also means headless/CI use needs a pre-generated token.json.
-
The credentials are secrets and .vibepaper/ is not gitignored. sync writes both credentials.json (the client secret) and token.json (a refresh token) into .vibepaper/. Neither vibepaper's own .gitignore nor any generated project template ignores .vibepaper/, so it is easy to commit secrets. A note (and ideally adding /.vibepaper/ to the project gitignore guidance) would help.
Suggested fix
A short "Setting up Google Docs sync" section in the README (or a docs/sync.md linked from it) with a step-by-step: enable Docs API, configure the OAuth consent screen (External + add yourself as a test user), create an OAuth client ID of type Desktop app, download the JSON and save it as .vibepaper/credentials.json, then run vibepaper sync for the first browser auth. Plus a one-line note that .vibepaper/ holds secrets and should be gitignored.
Happy to draft the section as a PR if that is useful.
Related to #2 (the sync feature this would document).
Problem
The
vibepaper syncfeature (#2) requires an OAuth client secret at.vibepaper/credentials.json, but the docs do not explain how to create one. The README and CHANGELOG both say only:For anyone who has not set up a Google Cloud OAuth client before, that one line leaves out every step that actually matters, and several of the steps are easy to get wrong in ways that fail late (only when you run
syncand hit the browser flow).What is non-obvious
While setting this up for a real project I hit or had to reason through the following, none of which is documented:
Which API to enable. Only the Google Docs API is needed (the code requests the single scope
https://www.googleapis.com/auth/documents). Drive API is not required. Without enabling Docs API the firstbatchUpdatefails.The OAuth client must be type "Desktop app". The auth code uses
InstalledAppFlow.from_client_secrets_file(...).run_local_server(port=0). A "Web application" client secret will not work with this flow. This is the single most likely thing to get wrong, and the resulting file looks superficially fine. (You can tell them apart: a Desktop secret has a top-level"installed"key, a Web one has"web".)The consent screen needs the user added as a test user. With an unpublished "External" app, authorization is rejected unless the authorizing account is listed under Test users. Publishing/verification is not required for personal use, but the test-user step is.
The first run is interactive and shows an "unverified app" warning.
run_local_serveropens a browser; because the app stays in Testing you get the "Google hasn't verified this app" screen and have to click Advanced then proceed. Worth saying so people do not assume something is broken. It also means headless/CI use needs a pre-generatedtoken.json.The credentials are secrets and
.vibepaper/is not gitignored.syncwrites bothcredentials.json(the client secret) andtoken.json(a refresh token) into.vibepaper/. Neither vibepaper's own.gitignorenor any generated project template ignores.vibepaper/, so it is easy to commit secrets. A note (and ideally adding/.vibepaper/to the project gitignore guidance) would help.Suggested fix
A short "Setting up Google Docs sync" section in the README (or a
docs/sync.mdlinked from it) with a step-by-step: enable Docs API, configure the OAuth consent screen (External + add yourself as a test user), create an OAuth client ID of type Desktop app, download the JSON and save it as.vibepaper/credentials.json, then runvibepaper syncfor the first browser auth. Plus a one-line note that.vibepaper/holds secrets and should be gitignored.Happy to draft the section as a PR if that is useful.
Related to #2 (the sync feature this would document).