docs(browserbase-cli): document --yes, --stdin, and agent-friendly patterns

skills/browserbase-cli/REFERENCE.md

@@ -115,7 +115,9 @@ bb projects usage <project_id>
 bb sessions list
 bb sessions list --q "user_metadata['userId']:'123'"
 bb sessions get <session_id>
+bb sessions create
 bb sessions create --body '{"projectId":"proj_123"}'
+echo '{"proxies":true}' | bb sessions create --stdin
 bb sessions update <session_id> --status REQUEST_RELEASE
 bb sessions debug <session_id>
 bb sessions logs <session_id>
@@ -124,12 +126,16 @@ bb sessions downloads get <session_id> --output session-artifacts.zip
 bb sessions uploads create <session_id> ./file.txt
 ```
 
+Use `--stdin` to pipe JSON from a file or another command instead of `--body`. Cannot use both together.
+
 When both `--status` and `--body` are present on `bb sessions update`, the CLI merges them.
 
 ### Contexts
 
 ```bash
-bb contexts create --body '{"region":"us-west-2"}'
+bb contexts create
+bb contexts create --body '{"projectId":"proj_123"}'
+echo '{"projectId":"proj_123"}' | bb contexts create --stdin
 bb contexts get <context_id>
 bb contexts update <context_id>
 bb contexts delete <context_id>
@@ -179,7 +185,13 @@ bb browse status
 bb browse open https://example.com
 ```
 
-If `browse` is not installed, the CLI will prompt you to install it:
+If `browse` is not installed, the CLI will prompt you to install it. Pass `--yes` to auto-accept the prompt (recommended for agents):
+
+```bash
+bb browse --yes status
+```
+
+Or install manually:
 
 ```bash
 npm install -g @browserbasehq/browse-cli
@@ -192,15 +204,15 @@ For most interactive browsing tasks, prefer the dedicated `browser` skill instea
 Install Browserbase agent skills for Claude Code directly from the CLI:
 
 ```bash
-bb skills install
+bb skills install       # non-interactive
+bb skills --yes         # auto-accept prompt
 ```
 
-This runs the skill installer non-interactively via npx.
-
 ## Troubleshooting
 
 - Missing API key: set `BROWSERBASE_API_KEY` or pass `--api-key`
 - Missing project ID on `bb functions dev` or `bb functions publish`: set `BROWSERBASE_PROJECT_ID` or pass `--project-id`
 - Wrong base URL flag: use `--api-url` for `bb functions ...`, `--base-url` for the other API commands
-- Invalid JSON input: wrap `--body` and `--params` payloads in single quotes so the shell preserves the JSON string
-- Browse passthrough missing: install `@browserbasehq/browse-cli` or use the `browser` skill directly
+- Invalid JSON input: wrap `--body` and `--params` payloads in single quotes so the shell preserves the JSON string, or use `--stdin` to pipe from a file
+- Browse passthrough missing: pass `--yes` to auto-install, or install `@browserbasehq/browse-cli` manually, or use the `browser` skill directly
+- Interactive prompt hanging: pass `--yes` to `bb browse` or `bb skills` to skip install prompts

skills/browserbase-cli/SKILL.md

@@ -95,15 +95,36 @@ bb search "web scraping" --num-results 5
 bb search "AI agents" --output results.json
 ```
 
+## Agent-friendly flags
+
+The CLI is designed for non-interactive use. Key flags for agents:
+
+- `--yes` / `-y` on `bb browse` and `bb skills` to skip interactive install prompts
+- `--stdin` on `bb sessions create`, `bb sessions update`, and `bb contexts create` to pipe JSON input instead of using `--body`
+- `--help` on every subcommand includes usage examples — run it to discover flags
+
+```bash
+# Skip install prompts (agents should always pass --yes)
+bb browse --yes --url https://example.com
+bb skills --yes
+
+# Pipe JSON via stdin instead of --body
+echo '{"proxies":true}' | bb sessions create --stdin
+cat config.json | bb contexts create --stdin
+
+# Cannot use both --body and --stdin together
+```
+
 ## Best practices
 
-1. Prefer `bb --help` and subgroup `--help` before guessing flags.
+1. Prefer `bb --help` and subgroup `--help` before guessing flags — every subcommand includes examples.
 2. Use dash-case flags exactly as shown in CLI help.
 3. Use `--output <file>` on `bb fetch` and `bb search` to save results to a file.
 4. Use environment variables for auth unless the user explicitly wants one-off overrides.
-5. Pass structured request bodies with JSON strings in `--body` or `--params`.
+5. Pass structured request bodies with JSON strings in `--body`, `--params`, or `--stdin`.
 6. Remember that `bb functions ...` uses `--api-url`, while platform API commands use `--base-url`.
-7. If `bb browse` fails because `browse` is missing, either install `@browserbasehq/browse-cli` or switch to the `browser` skill.
+7. Use `--yes` when invoking `bb browse` or `bb skills` non-interactively to avoid hanging on install prompts.
+8. If `bb browse` fails because `browse` is missing, pass `--yes` to auto-install, or install `@browserbasehq/browse-cli` manually.
 
 ## Troubleshooting