just-bash-gdrive 0.1.0 → 0.1.2

package/README.md

@@ -6,6 +6,22 @@ Lets AI agents interact with Google Drive files using standard bash commands (`l
 
 Inspired by [just-bash-dropbox](https://github.com/manishrc/just-bash-dropbox) — the same pattern, applied to Google Drive.
 
+## Why not just use the Drive API or gogcli?
+
+Tools like [gogcli](https://github.com/steipete/gogcli) are great when *you* know exactly what you want to do with Drive. You write the specific command, it runs.
+
+`just-bash-gdrive` is for when you want to hand an *agent* the ability to figure that out — and do it safely.
+
+**Compositional bash logic at runtime.** An LLM can write arbitrary pipelines on the fly — `find / -name "*.md" | xargs grep "keyword" | sort` — without you anticipating every possible query in advance. No new API code per use case.
+
+**Drive as a mountable filesystem.** `MountableFs` lets you compose Drive with other filesystems. An agent works across `/drive` (real files) and `/tmp` (scratch space) in the same bash session. The Drive API has no composability story.
+
+**Safe exploration mode.** Mount Drive read-only — the agent can `cat`, `grep`, and `find` freely with zero write risk. There's no equivalent in any Drive CLI.
+
+**AI SDK tool wrapper.** The `bash-tool` package from just-bash wraps the whole thing as a single LLM tool. One line to give any model bash access to Drive.
+
+**The rule of thumb:** use gogcli when you're writing the script. Use just-bash-gdrive when the agent is writing the script.
+
 ## Install
 
 ```bash
@@ -76,7 +92,32 @@ const { text } = await generateText({
 
 ### Getting an access token
 
-Use your preferred Google OAuth2 library. The `accessToken` option accepts either a static string or an async function — use the async form for long-running agents so the token refreshes automatically:
+The `accessToken` option accepts either a static string or an async function — use the async form for long-running agents so the token refreshes automatically.
+
+**Option 1: [gogcli](https://github.com/steipete/gogcli) (recommended for quick setup)**
+
+gogcli handles Google OAuth2 authentication and stores tokens locally. After running `gog auth login`, you can retrieve tokens programmatically:
+
+```bash
+# Install gogcli
+npm install -g gogcli
+
+# Authenticate (opens browser)
+gog auth login
+```
+
+```ts
+import { execSync } from "child_process";
+
+const fs = new GDriveFs({
+  accessToken: () => {
+    // gogcli outputs a fresh token to stdout
+    return execSync("gog auth token", { encoding: "utf8" }).trim();
+  },
+});
+```
+
+**Option 2: googleapis (full OAuth2 flow)**
 
 ```ts
 import { google } from "googleapis";
@@ -92,6 +133,14 @@ const fs = new GDriveFs({
 });
 ```
 
+**Option 3: Static token (scripts and testing)**
+
+For short-lived scripts, pass a token directly. Get one via `gog auth token` or the [OAuth2 Playground](https://developers.google.com/oauthplayground).
+
+```ts
+const fs = new GDriveFs({ accessToken: "ya29.your_token_here" });
+```
+
 ## Options
 
 | Option | Type | Default | Description |
@@ -110,7 +159,7 @@ Rate limit handling: automatically retries on HTTP 429 with `Retry-After` backof
 - `chmod`, `symlink`, `link`, `readlink`, `utimes` throw `ENOSYS` — Drive has no POSIX permission or symlink concept
 - `getAllPaths()` returns `[]` until `prefetchAllPaths()` is called — glob operations require prefetch
 - `appendFile` reads the existing file, appends, then rewrites — Drive has no atomic append
-- Google Workspace files (Docs, Sheets, Slides) cannot be read as raw content; use `gog-andy` or the Drive export API for those
+- Google Workspace files (Docs, Sheets, Slides) cannot be read as raw content; use `gog export` (gogcli) or the Drive export API to convert them first
 
 ## Inspiration
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "just-bash-gdrive",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Google Drive filesystem adapter for just-bash",
   "type": "module",
   "license": "Apache-2.0",