feedbackbasket-cli 3.0.0 → 3.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (10) hide show
  1. package/CHANGELOG.md +290 -274
  2. package/README.md +340 -336
  3. package/dist/src/auth/login.d.ts +4 -3
  4. package/dist/src/auth/login.js +70 -43
  5. package/dist/src/capabilities.d.ts +4 -0
  6. package/dist/src/commands/auth.d.ts +9 -3
  7. package/dist/src/commands/auth.js +100 -93
  8. package/dist/src/version.d.ts +1 -1
  9. package/package.json +54 -54
  10. package/skills/feedbackbasket/SKILL.md +407 -377
package/README.md CHANGED
@@ -1,61 +1,63 @@
1
- # FeedbackBasket CLI
2
-
3
- Command-line interface for [FeedbackBasket](https://feedbackbasket.com) — manage feedback, bug reports, projects, and widgets from your terminal or through AI agents.
4
-
5
- Inspired by the [Basecamp CLI](https://github.com/basecamp/basecamp-cli). Everything you can do in the dashboard, you can do from the CLI.
6
-
7
- ## Quick Start
8
-
9
- ```bash
10
- # Install
11
- npm install -g feedbackbasket-cli
12
-
13
- # Authenticate (opens browser, full access by default)
14
- feedbackbasket login
15
-
16
- # Or use a token directly (for CI/headless)
17
- feedbackbasket login --token fb_cli_your_token_here
18
-
19
- # Remote server flow: use when localhost browser callbacks cannot reach the CLI
20
- feedbackbasket login --manual
21
-
22
- # Start exploring
23
- feedbackbasket projects list
24
- feedbackbasket feedback list
25
- feedbackbasket feedback create "Login button is broken" --project myapp --type bug
26
- feedbackbasket bugs list --severity high
27
- ```
28
-
1
+ # FeedbackBasket CLI
2
+
3
+ Command-line interface for [FeedbackBasket](https://feedbackbasket.com) — manage feedback, bug reports, projects, and widgets from your terminal or through AI agents.
4
+
5
+ Inspired by the [Basecamp CLI](https://github.com/basecamp/basecamp-cli). Everything you can do in the dashboard, you can do from the CLI.
6
+
7
+ ## Quick Start
8
+
9
+ ```bash
10
+ # Install
11
+ npm install -g feedbackbasket-cli
12
+
13
+ # Authenticate (the browser selects Read or Full access)
14
+ feedbackbasket login
15
+
16
+ # Or use a token directly (for CI/headless)
17
+ feedbackbasket login --token fb_cli_your_token_here
18
+
19
+ # Remote server flow: use when localhost browser callbacks cannot reach the CLI
20
+ feedbackbasket login --manual
21
+
22
+ # Start exploring
23
+ feedbackbasket projects list
24
+ feedbackbasket feedback list
25
+ feedbackbasket feedback create "Login button is broken" --project myapp --type bug
26
+ feedbackbasket bugs list --severity high
27
+ ```
28
+
29
+ The browser selects the organization, Read or Full access, and Selected projects or All projects. Read is selected by default. Full needs an explicit choice and an owner or administrator role. Selected projects limits the token to approved projects. All projects includes current and future projects and is required for project creation and team operations. The `--scope read|full` option sets the maximum browser access. It does not make the final choice.
30
+
29
31
  The first time you log in, a setup wizard walks you through selecting a default project and installing the Claude Code skill.
30
32
 
31
- The CLI uses agent surface version `3.0.0`. CLI login accepts only private CLI credentials. It does not accept MCP keys. Use `--yes` for high-impact commands in agent or machine mode. Interactive use can show a confirmation prompt.
32
-
33
- ## Agent Usage
34
-
35
- Any AI agent with shell access (Claude Code, Codex, Cursor, OpenCode) can use the CLI directly:
36
-
37
- ```bash
38
- # Agents should use --agent flag for raw JSON output
39
- feedbackbasket projects list --agent
40
- feedbackbasket feedback list --category BUG --agent
41
- feedbackbasket feedback create "Login button is broken" --content "Clicking Log in does nothing in Safari." --project myapp --type bug --agent
42
- feedbackbasket feedback update <id> --status PLANNED --agent
43
- feedbackbasket widget script myproject --agent
44
- feedbackbasket mobile setup myproject --bundle-id com.example.app --include-publishable-key --agent
45
- ```
46
-
47
- When installing or configuring a widget for the current app, agents should not rely on the CLI default project. First run `feedbackbasket projects list --agent`, match the current app by its real website URL or clearly matching project name, and only create a new project after confirming no existing project belongs to this app. If the only known URL is `localhost`, ask for the production, staging, preview, or intended public URL before creating the project.
48
-
49
- ### Install Claude Code Skill
50
-
51
- ```bash
52
- feedbackbasket setup claude
53
- ```
54
-
33
+ The CLI uses agent surface version `3.1.0`. CLI login accepts only private CLI credentials. It does not accept MCP keys or OAuth tokens. Use `--yes` for high-impact commands in agent or machine mode. Interactive use can show a confirmation prompt. Never put an access token, refresh token, CLI token, or MCP key in source, prompts, logs, generated configuration, or final output.
34
+
35
+ ## Agent Usage
36
+
37
+ Any AI agent with shell access (Claude Code, Codex, Cursor, OpenCode) can use the CLI directly:
38
+
39
+ ```bash
40
+ # Agents should use --agent flag for raw JSON output
41
+ feedbackbasket projects list --agent
42
+ feedbackbasket feedback list --category BUG --agent
43
+ feedbackbasket feedback create "Login button is broken" --content "Clicking Log in does nothing in Safari." --project myapp --type bug --agent
44
+ feedbackbasket feedback update <id> --status PLANNED --agent
45
+ feedbackbasket widget script myproject --agent
46
+ feedbackbasket mobile setup myproject --bundle-id com.example.app --include-publishable-key --agent
47
+ ```
48
+
49
+ When installing or configuring a widget for the current app, agents should not rely on the CLI default project. First run `feedbackbasket projects list --agent`, match the current app by its real website URL or clearly matching project name, and only create a new project after confirming no existing project belongs to this app. If the only known URL is `localhost`, ask for the production, staging, preview, or intended public URL before creating the project.
50
+
51
+ ### Install Claude Code Skill
52
+
53
+ ```bash
54
+ feedbackbasket setup claude
55
+ ```
56
+
55
57
  <!-- BEGIN GENERATED AGENT CAPABILITIES -->
56
58
  ## Agent capability contract
57
59
 
58
- Agent surface version: `3.0.0`. The CLI and both MCP transports implement the same 31 product operations.
60
+ Agent surface version: `3.1.0`. The CLI and both MCP transports implement the same 31 product operations.
59
61
 
60
62
  | Product operation | CLI command | MCP tool | Required access | Confirm |
61
63
  | --- | --- | --- | --- | --- |
@@ -93,286 +95,288 @@ Agent surface version: `3.0.0`. The CLI and both MCP transports implement the sa
93
95
  <!-- END GENERATED AGENT CAPABILITIES -->
94
96
 
95
97
  ## Commands
96
-
97
- ### Authentication
98
-
99
- ```bash
100
- feedbackbasket login # Browser OAuth flow (alias for auth login)
101
- feedbackbasket login --manual # No localhost browser callback (remote servers)
102
- feedbackbasket login --token <token> # Use an existing CLI token (CI / scripts)
103
- feedbackbasket logout # Clear credentials (alias for auth logout)
104
- feedbackbasket auth status # Show auth state, scope, default project
105
- feedbackbasket auth token # Print raw token (for scripting/piping)
106
- ```
107
-
108
- CLI tokens start with `fb_cli_`. MCP API keys start with `fb_key_` and are only for MCP server configuration.
109
-
110
- ### Projects
111
-
112
- All project commands accept **name or ID** (e.g. `feedbackbasket` or `cmn3c7sgv...`).
113
-
114
- ```bash
115
- feedbackbasket projects list # List all projects with stats
116
- feedbackbasket projects show <name-or-id> # Project details
117
- feedbackbasket projects create "My App" --url https://... # Create project
118
- feedbackbasket projects create "Local Test" --url http://localhost:3000 --allow-local-url
119
- feedbackbasket projects update myapp --name "New Name" # Update project
120
- feedbackbasket projects update myapp --reply-to vlad@example.com # Set default reply-to email
121
- feedbackbasket projects delete myapp # Delete (with confirmation)
122
- ```
123
-
124
- Use the production, staging, preview, or intended public website URL for projects. The CLI blocks accidental `localhost`/loopback URLs in agent and non-interactive mode unless you pass `--allow-local-url` for an explicitly local-only test project.
125
-
126
- ### Feedback
127
-
128
- ```bash
129
- # Read
130
- feedbackbasket feedback list # List recent feedback
131
- feedbackbasket feedback list --project myapp # Filter by project
132
- feedbackbasket feedback list --category BUG # Filter by category
133
- feedbackbasket feedback list --status OPEN # Filter by status
134
- feedbackbasket feedback list --sentiment NEGATIVE # Filter by sentiment
135
- feedbackbasket feedback list --search "login issue" # Text search
136
- feedbackbasket feedback show <id> # View detail, including attachment links
137
- feedbackbasket feedback search "crash on mobile" # Search shortcut
138
-
139
- # Write
140
- feedbackbasket feedback create "Title" --content "Body" --project myapp
141
- feedbackbasket feedback create "Login bug" --content "Clicking Log in does nothing" --project myapp --type bug --page-url https://example.com/login
142
- feedbackbasket feedback update <id> --status PLANNED # Update status
143
- feedbackbasket feedback update <id> --category BUG # Update category
144
- feedbackbasket feedback reply <id> "Thanks!" --delivery email --reply-to support@example.com
145
- feedbackbasket feedback reply <id> "Thanks!" --delivery widget
146
- feedbackbasket feedback reply <id> "Thanks!" --delivery in-app
147
- feedbackbasket feedback reply <id> "Thanks!" --delivery both --reply-to support@example.com
148
- feedbackbasket feedback replies <id> # Show the complete conversation
149
- feedbackbasket feedback note <id> "Investigating this..." # Add internal note
150
- feedbackbasket feedback delete <id> # Delete feedback
151
- feedbackbasket feedback bulk-update --status CLOSED --ids id1,id2,id3
152
-
153
- # Export
154
- feedbackbasket feedback export myapp --format csv # Export to CSV
155
- feedbackbasket feedback export myapp --format md # Export to Markdown
156
- feedbackbasket feedback export myapp --format json # Export to JSON
157
- ```
158
-
159
- ### Bug Reports
160
-
161
- ```bash
162
- feedbackbasket bugs list # All bugs
163
- feedbackbasket bugs list --severity high # High severity only
164
- feedbackbasket bugs list --status OPEN # Open bugs
165
- feedbackbasket bugs stats # Bug statistics summary
166
- feedbackbasket bugs stats --project myapp # Per-project stats
167
- ```
168
-
169
- ### Widget
170
-
171
- ```bash
172
- # View current settings
173
- feedbackbasket widget settings myapp
174
-
175
- # Update widget configuration
176
- feedbackbasket widget settings myapp --capture-mode waitlist
177
- feedbackbasket widget settings myapp --capture-mode feedback
178
- feedbackbasket widget settings myapp --color "#22c55e" --label "Send Feedback"
179
- feedbackbasket widget settings myapp --position bottom-left --display modal
180
- feedbackbasket widget settings myapp --email-required --intro "How can we improve?"
181
- feedbackbasket widget settings myapp --button-radius 10 --button-size regular
182
- feedbackbasket widget settings myapp --show-email --allow-attachments
183
- feedbackbasket widget settings myapp --allow-visitor-replies
184
- feedbackbasket widget settings myapp --no-allow-visitor-replies
185
- feedbackbasket widget settings myapp --email-read-only --hide-email-when-prefilled
186
- feedbackbasket widget settings myapp --error-tracking --allow-console-errors
187
-
188
- # Configure guided feedback types and follow-up questions
189
- feedbackbasket widget flow myapp
190
- feedbackbasket widget flow myapp --enable # guided only when requested
191
- feedbackbasket widget flow myapp --reset-default --enable # guided only when requested
192
- feedbackbasket widget flow myapp --config ./feedback-flow.json
193
-
194
- # Get embed code (ready to paste into your HTML)
195
- feedbackbasket widget script myapp
196
- ```
197
-
198
- Waitlist mode uses the same project script. Add `data-feedbackbasket-waitlist` to your own form, with a required `email` field and optional `name` field. The CLI's `widget script` output shows a starter form when waitlist mode is active.
199
-
200
- ### Waitlist
201
-
202
- ```bash
203
- feedbackbasket waitlist list myapp
204
- feedbackbasket waitlist list myapp --search "@example.com" --limit 50 --offset 0
205
- feedbackbasket waitlist list myapp --agent
206
- feedbackbasket waitlist export myapp
207
- ```
208
-
209
- Waitlist listing returns emails, optional names, source pages, total counts, the active capture mode, and pagination. Export prints the dashboard-compatible CSV to stdout.
210
-
211
- For inline trigger mode, load the widget once and call the public API from your own button:
212
-
213
- ```html
214
- <button onclick="window.FeedbackWidget.openFeedbackForm({ trigger: event.currentTarget })">
215
- Feedback
216
- </button>
217
- ```
218
-
219
- Passing the trigger element lets popup mode open beside your custom button. Calling `window.FeedbackWidget.openFeedbackForm()` with no arguments still uses the configured widget position.
220
-
221
- Use only the public `openFeedbackForm()` API from the snippet. Do not call internal or undocumented methods such as `open()` or `openModal()`.
222
-
223
- Use `--email-read-only` and `--hide-email-when-prefilled` with runtime `userEmail` values from your app. These settings do not store visitor emails in FeedbackBasket widget settings.
224
-
225
- The default widget experience is a basic modal. Only switch to popup mode or enable guided feedback when you intentionally want that flow.
226
-
227
- `widget flow --config` accepts either a `feedbackFlow` object or a JSON object with a `feedbackFlow` key. V1 supports guided mode with `text`, `textarea`, and `single_choice` follow-up questions.
228
-
229
- ```json
230
- {
231
- "enabled": true,
232
- "mode": "guided",
233
- "types": [
234
- {
235
- "id": "bug",
236
- "emoji": "🐞",
237
- "label": "Bug report",
238
- "description": "Something is broken or not working",
239
- "questions": [
240
- {
241
- "id": "steps",
242
- "label": "What steps can reproduce it?",
243
- "type": "textarea"
244
- }
245
- ]
246
- }
247
- ]
248
- }
249
- ```
250
-
251
- ### Mobile Apps
252
-
253
- Mobile setup is additive and does not change the website widget. The `fb_mobile_` value is a publishable, write-only project identifier designed to ship in an app; it is not a CLI token or private API key. Mobile commands mask it unless `--include-publishable-key` is explicitly supplied.
254
-
255
- ```bash
256
- # Enable mobile feedback and add allowed iOS bundle IDs
257
- feedbackbasket mobile setup myapp --bundle-id com.example.app
258
-
259
- # Return the publishable key and hosted form URL for an authorized app setup
260
- feedbackbasket mobile setup myapp --bundle-id com.example.app --include-publishable-key --agent
261
-
262
- # Inspect and verify the SDK heartbeat
263
- feedbackbasket mobile status myapp
264
- feedbackbasket mobile verify myapp --bundle-id com.example.app --wait 120
265
-
266
- # Let users answer team replies in the original in-app conversation
267
- feedbackbasket mobile conversations myapp --enable
268
- feedbackbasket mobile conversations myapp --disable
269
-
270
- # Add or remove bundle IDs without replacing the others
271
- feedbackbasket mobile bundle-ids myapp --add com.example.app.beta
272
- feedbackbasket mobile bundle-ids myapp --remove com.example.app.beta
273
-
274
- # Actions that can interrupt installed apps require explicit confirmation
275
- feedbackbasket mobile disable myapp --yes
276
- feedbackbasket mobile rotate-key myapp --yes --include-publishable-key
277
- ```
278
-
279
- Agents should never repeat the full publishable key in their final response. They must never place `fb_cli_` or `fb_key_` credentials in a mobile app. Key rotation invalidates the previous key and therefore requires explicit user authorization.
280
-
281
- The native Swift SDK securely stores conversation credentials in the app Keychain, shows an unread badge when the team replies, and lets users answer inside the same thread when mobile conversations are enabled. Host apps do not need to build an inbox or manage reply tokens. Hosted-form integrations remain email-only. Website widget follow-up replies are configured independently with `widget settings`.
282
-
283
- ### Team
284
-
285
- ```bash
286
- feedbackbasket team list # List organization members
287
- feedbackbasket team role <memberId> --role admin # Update member role
288
- feedbackbasket team remove <memberId> # Remove member
289
- ```
290
-
291
- ### Utilities
292
-
293
- ```bash
294
- feedbackbasket doctor # Run diagnostics (auth, connectivity, integrations)
295
- feedbackbasket setup claude # Install Claude Code skill
296
- ```
297
-
298
- ## Output Modes
299
-
300
- The CLI automatically detects your environment:
301
-
302
- | Context | Behavior |
303
- |---------|----------|
304
- | **Terminal (TTY)** | Styled, human-readable output with FeedbackBasket brand colors |
305
- | **Piped** | JSON output automatically |
306
- | `--json` | Full JSON envelope with breadcrumbs |
307
- | `--quiet` / `--agent` | Raw JSON data only (no envelope) |
308
- | `--md` | Markdown formatted |
309
-
310
- ### JSON Envelope
311
-
312
- ```json
313
- {
314
- "ok": true,
315
- "data": [...],
316
- "summary": "12 open bugs, 3 high severity",
317
- "breadcrumbs": [
318
- { "action": "View high severity", "cmd": "feedbackbasket bugs list --severity high" }
319
- ]
320
- }
321
- ```
322
-
323
- Breadcrumbs suggest the next logical command — useful for both humans and agents navigating without a full command catalog.
324
-
325
- ## Configuration
326
-
327
- Credentials stored in `~/.config/feedbackbasket/credentials.json`. Config in `~/.config/feedbackbasket/config.json`.
328
-
329
- ### Default Project
330
-
331
- Set during the login wizard, or manually:
332
-
333
- ```bash
334
- # Commands auto-scope to your default project
335
- feedbackbasket feedback list # uses default project
336
- feedbackbasket feedback list --project other-app # override
337
- ```
338
-
339
- ### Environment Variables
340
-
341
- | Variable | Description |
342
- |----------|-------------|
343
- | `FEEDBACKBASKET_TOKEN` | CLI token (bypasses stored credentials) |
344
- | `FEEDBACKBASKET_BASE_URL` | API base URL override |
345
-
346
- ### Global Flags
347
-
348
- | Flag | Description |
349
- |------|-------------|
350
- | `--json` | Full JSON envelope output |
351
- | `--quiet` / `--agent` | Raw JSON data only |
352
- | `--md` | Markdown output |
353
- | `--base-url <url>` | Override API base URL |
354
-
355
- ## Filter Options
356
-
357
- | Type | Values |
358
- |------|--------|
359
- | **Categories** | `BUG`, `FEATURE_REQUEST`, `IMPROVEMENT`, `QUESTION` |
360
- | **Statuses** | `OPEN`, `UNDER_REVIEW`, `PLANNED`, `IN_PROGRESS`, `COMPLETE`, `CLOSED` |
361
- | **Sentiments** | `POSITIVE`, `NEGATIVE`, `NEUTRAL` |
362
- | **Bug Severity** | `high`, `medium`, `low` |
363
-
364
- ## Development
365
-
366
- ```bash
367
- git clone https://github.com/deifos/feedbackbasket-cli.git
368
- cd feedbackbasket-cli
369
- npm install
370
- npm run dev -- --help # Run in development
371
- npm run build # Build for production
372
- npm run dev -- login # Test login flow
373
- npm run dev -- doctor # Test diagnostics
374
- ```
375
-
376
- ## License
377
-
378
- MIT
98
+
99
+ ### Authentication
100
+
101
+ ```bash
102
+ feedbackbasket login # Browser OAuth flow (alias for auth login)
103
+ feedbackbasket login --manual # No localhost browser callback (remote servers)
104
+ feedbackbasket login --token <token> # Use an existing CLI token (CI / scripts)
105
+ feedbackbasket logout # Clear credentials (alias for auth logout)
106
+ feedbackbasket auth status # Show auth state, scope, default project
107
+ feedbackbasket auth token # Print raw token (for scripting/piping)
108
+ ```
109
+
110
+ CLI tokens start with `fb_cli_`. MCP API keys start with `fb_key_` and are only for MCP server configuration.
111
+
112
+ ### Projects
113
+
114
+ All project commands accept **name or ID** (e.g. `feedbackbasket` or `cmn3c7sgv...`).
115
+
116
+ ```bash
117
+ feedbackbasket projects list # List all projects with stats
118
+ feedbackbasket projects show <name-or-id> # Project details
119
+ feedbackbasket projects create "My App" --url https://... # Create project
120
+ feedbackbasket projects create "Local Test" --url http://localhost:3000 --allow-local-url
121
+ feedbackbasket projects update myapp --name "New Name" # Update project
122
+ feedbackbasket projects update myapp --reply-to vlad@example.com # Set default reply-to email
123
+ feedbackbasket projects delete myapp # Delete (with confirmation)
124
+ ```
125
+
126
+ Use the production, staging, preview, or intended public website URL for projects. The CLI blocks accidental `localhost`/loopback URLs in agent and non-interactive mode unless you pass `--allow-local-url` for an explicitly local-only test project.
127
+
128
+ ### Feedback
129
+
130
+ ```bash
131
+ # Read
132
+ feedbackbasket feedback list # List recent feedback
133
+ feedbackbasket feedback list --project myapp # Filter by project
134
+ feedbackbasket feedback list --category BUG # Filter by category
135
+ feedbackbasket feedback list --status OPEN # Filter by status
136
+ feedbackbasket feedback list --sentiment NEGATIVE # Filter by sentiment
137
+ feedbackbasket feedback list --search "login issue" # Text search
138
+ feedbackbasket feedback show <id> # View detail, including attachment links
139
+ feedbackbasket feedback search "crash on mobile" # Search shortcut
140
+
141
+ # Write
142
+ feedbackbasket feedback create "Title" --content "Body" --project myapp
143
+ feedbackbasket feedback create "Login bug" --content "Clicking Log in does nothing" --project myapp --type bug --page-url https://example.com/login
144
+ feedbackbasket feedback update <id> --status PLANNED # Update status
145
+ feedbackbasket feedback update <id> --category BUG # Update category
146
+ feedbackbasket feedback reply <id> "Thanks!" --delivery email --reply-to support@example.com
147
+ feedbackbasket feedback reply <id> "Thanks!" --delivery widget
148
+ feedbackbasket feedback reply <id> "Thanks!" --delivery in-app
149
+ feedbackbasket feedback reply <id> "Thanks!" --delivery both --reply-to support@example.com
150
+ feedbackbasket feedback replies <id> # Show the complete conversation
151
+ feedbackbasket feedback note <id> "Investigating this..." # Add internal note
152
+ feedbackbasket feedback delete <id> # Delete feedback
153
+ feedbackbasket feedback bulk-update --status CLOSED --ids id1,id2,id3
154
+
155
+ # Export
156
+ feedbackbasket feedback export myapp --format csv # Export to CSV
157
+ feedbackbasket feedback export myapp --format md # Export to Markdown
158
+ feedbackbasket feedback export myapp --format json # Export to JSON
159
+ ```
160
+
161
+ ### Bug Reports
162
+
163
+ ```bash
164
+ feedbackbasket bugs list # All bugs
165
+ feedbackbasket bugs list --severity high # High severity only
166
+ feedbackbasket bugs list --status OPEN # Open bugs
167
+ feedbackbasket bugs stats # Bug statistics summary
168
+ feedbackbasket bugs stats --project myapp # Per-project stats
169
+ ```
170
+
171
+ ### Widget
172
+
173
+ ```bash
174
+ # View current settings
175
+ feedbackbasket widget settings myapp
176
+
177
+ # Update widget configuration
178
+ feedbackbasket widget settings myapp --capture-mode waitlist
179
+ feedbackbasket widget settings myapp --capture-mode feedback
180
+ feedbackbasket widget settings myapp --color "#22c55e" --label "Send Feedback"
181
+ feedbackbasket widget settings myapp --position bottom-left --display modal
182
+ feedbackbasket widget settings myapp --email-required --intro "How can we improve?"
183
+ feedbackbasket widget settings myapp --button-radius 10 --button-size regular
184
+ feedbackbasket widget settings myapp --show-email --allow-attachments
185
+ feedbackbasket widget settings myapp --allow-visitor-replies
186
+ feedbackbasket widget settings myapp --no-allow-visitor-replies
187
+ feedbackbasket widget settings myapp --email-read-only --hide-email-when-prefilled
188
+ feedbackbasket widget settings myapp --error-tracking --allow-console-errors
189
+
190
+ # Configure guided feedback types and follow-up questions
191
+ feedbackbasket widget flow myapp
192
+ feedbackbasket widget flow myapp --enable # guided only when requested
193
+ feedbackbasket widget flow myapp --reset-default --enable # guided only when requested
194
+ feedbackbasket widget flow myapp --config ./feedback-flow.json
195
+
196
+ # Get embed code (ready to paste into your HTML)
197
+ feedbackbasket widget script myapp
198
+ ```
199
+
200
+ Waitlist mode uses the same project script. Add `data-feedbackbasket-waitlist` to your own form, with a required `email` field and optional `name` field. The CLI's `widget script` output shows a starter form when waitlist mode is active.
201
+
202
+ ### Waitlist
203
+
204
+ ```bash
205
+ feedbackbasket waitlist list myapp
206
+ feedbackbasket waitlist list myapp --search "@example.com" --limit 50 --offset 0
207
+ feedbackbasket waitlist list myapp --agent
208
+ feedbackbasket waitlist export myapp
209
+ ```
210
+
211
+ Waitlist listing returns emails, optional names, source pages, total counts, the active capture mode, and pagination. Export prints the dashboard-compatible CSV to stdout.
212
+
213
+ For inline trigger mode, load the widget once and call the public API from your own button:
214
+
215
+ ```html
216
+ <button
217
+ onclick="window.FeedbackWidget.openFeedbackForm({ trigger: event.currentTarget })"
218
+ >
219
+ Feedback
220
+ </button>
221
+ ```
222
+
223
+ Passing the trigger element lets popup mode open beside your custom button. Calling `window.FeedbackWidget.openFeedbackForm()` with no arguments still uses the configured widget position.
224
+
225
+ Use only the public `openFeedbackForm()` API from the snippet. Do not call internal or undocumented methods such as `open()` or `openModal()`.
226
+
227
+ Use `--email-read-only` and `--hide-email-when-prefilled` with runtime `userEmail` values from your app. These settings do not store visitor emails in FeedbackBasket widget settings.
228
+
229
+ The default widget experience is a basic modal. Only switch to popup mode or enable guided feedback when you intentionally want that flow.
230
+
231
+ `widget flow --config` accepts either a `feedbackFlow` object or a JSON object with a `feedbackFlow` key. V1 supports guided mode with `text`, `textarea`, and `single_choice` follow-up questions.
232
+
233
+ ```json
234
+ {
235
+ "enabled": true,
236
+ "mode": "guided",
237
+ "types": [
238
+ {
239
+ "id": "bug",
240
+ "emoji": "🐞",
241
+ "label": "Bug report",
242
+ "description": "Something is broken or not working",
243
+ "questions": [
244
+ {
245
+ "id": "steps",
246
+ "label": "What steps can reproduce it?",
247
+ "type": "textarea"
248
+ }
249
+ ]
250
+ }
251
+ ]
252
+ }
253
+ ```
254
+
255
+ ### Mobile Apps
256
+
257
+ Mobile setup is additive and does not change the website widget. The `fb_mobile_` value is a publishable, write-only project identifier designed to ship in an app; it is not a CLI token or private API key. Mobile commands mask it unless `--include-publishable-key` is explicitly supplied.
258
+
259
+ ```bash
260
+ # Enable mobile feedback and add allowed iOS bundle IDs
261
+ feedbackbasket mobile setup myapp --bundle-id com.example.app
262
+
263
+ # Return the publishable key and hosted form URL for an authorized app setup
264
+ feedbackbasket mobile setup myapp --bundle-id com.example.app --include-publishable-key --agent
265
+
266
+ # Inspect and verify the SDK heartbeat
267
+ feedbackbasket mobile status myapp
268
+ feedbackbasket mobile verify myapp --bundle-id com.example.app --wait 120
269
+
270
+ # Let users answer team replies in the original in-app conversation
271
+ feedbackbasket mobile conversations myapp --enable
272
+ feedbackbasket mobile conversations myapp --disable
273
+
274
+ # Add or remove bundle IDs without replacing the others
275
+ feedbackbasket mobile bundle-ids myapp --add com.example.app.beta
276
+ feedbackbasket mobile bundle-ids myapp --remove com.example.app.beta
277
+
278
+ # Actions that can interrupt installed apps require explicit confirmation
279
+ feedbackbasket mobile disable myapp --yes
280
+ feedbackbasket mobile rotate-key myapp --yes --include-publishable-key
281
+ ```
282
+
283
+ Agents should never repeat the full publishable key in their final response. They must never place `fb_cli_` or `fb_key_` credentials in a mobile app. Key rotation invalidates the previous key and therefore requires explicit user authorization.
284
+
285
+ The native Swift SDK securely stores conversation credentials in the app Keychain, shows an unread badge when the team replies, and lets users answer inside the same thread when mobile conversations are enabled. Host apps do not need to build an inbox or manage reply tokens. Hosted-form integrations remain email-only. Website widget follow-up replies are configured independently with `widget settings`.
286
+
287
+ ### Team
288
+
289
+ ```bash
290
+ feedbackbasket team list # List organization members
291
+ feedbackbasket team role <memberId> --role admin # Update member role
292
+ feedbackbasket team remove <memberId> # Remove member
293
+ ```
294
+
295
+ ### Utilities
296
+
297
+ ```bash
298
+ feedbackbasket doctor # Run diagnostics (auth, connectivity, integrations)
299
+ feedbackbasket setup claude # Install Claude Code skill
300
+ ```
301
+
302
+ ## Output Modes
303
+
304
+ The CLI automatically detects your environment:
305
+
306
+ | Context | Behavior |
307
+ | --------------------- | -------------------------------------------------------------- |
308
+ | **Terminal (TTY)** | Styled, human-readable output with FeedbackBasket brand colors |
309
+ | **Piped** | JSON output automatically |
310
+ | `--json` | Full JSON envelope with breadcrumbs |
311
+ | `--quiet` / `--agent` | Raw JSON data only (no envelope) |
312
+ | `--md` | Markdown formatted |
313
+
314
+ ### JSON Envelope
315
+
316
+ ```json
317
+ {
318
+ "ok": true,
319
+ "data": [...],
320
+ "summary": "12 open bugs, 3 high severity",
321
+ "breadcrumbs": [
322
+ { "action": "View high severity", "cmd": "feedbackbasket bugs list --severity high" }
323
+ ]
324
+ }
325
+ ```
326
+
327
+ Breadcrumbs suggest the next logical command — useful for both humans and agents navigating without a full command catalog.
328
+
329
+ ## Configuration
330
+
331
+ Credentials stored in `~/.config/feedbackbasket/credentials.json`. Config in `~/.config/feedbackbasket/config.json`.
332
+
333
+ ### Default Project
334
+
335
+ Set during the login wizard, or manually:
336
+
337
+ ```bash
338
+ # Commands auto-scope to your default project
339
+ feedbackbasket feedback list # uses default project
340
+ feedbackbasket feedback list --project other-app # override
341
+ ```
342
+
343
+ ### Environment Variables
344
+
345
+ | Variable | Description |
346
+ | ------------------------- | --------------------------------------- |
347
+ | `FEEDBACKBASKET_TOKEN` | CLI token (bypasses stored credentials) |
348
+ | `FEEDBACKBASKET_BASE_URL` | API base URL override |
349
+
350
+ ### Global Flags
351
+
352
+ | Flag | Description |
353
+ | --------------------- | ------------------------- |
354
+ | `--json` | Full JSON envelope output |
355
+ | `--quiet` / `--agent` | Raw JSON data only |
356
+ | `--md` | Markdown output |
357
+ | `--base-url <url>` | Override API base URL |
358
+
359
+ ## Filter Options
360
+
361
+ | Type | Values |
362
+ | ---------------- | ---------------------------------------------------------------------- |
363
+ | **Categories** | `BUG`, `FEATURE_REQUEST`, `IMPROVEMENT`, `QUESTION` |
364
+ | **Statuses** | `OPEN`, `UNDER_REVIEW`, `PLANNED`, `IN_PROGRESS`, `COMPLETE`, `CLOSED` |
365
+ | **Sentiments** | `POSITIVE`, `NEGATIVE`, `NEUTRAL` |
366
+ | **Bug Severity** | `high`, `medium`, `low` |
367
+
368
+ ## Development
369
+
370
+ ```bash
371
+ git clone https://github.com/deifos/feedbackbasket-cli.git
372
+ cd feedbackbasket-cli
373
+ npm install
374
+ npm run dev -- --help # Run in development
375
+ npm run build # Build for production
376
+ npm run dev -- login # Test login flow
377
+ npm run dev -- doctor # Test diagnostics
378
+ ```
379
+
380
+ ## License
381
+
382
+ MIT