FeedbackBasket CLI

Command-line interface for FeedbackBasket — manage feedback, bug reports, projects, and widgets from your terminal or through AI agents.

Inspired by the Basecamp CLI. Everything you can do in the dashboard, you can do from the CLI.

Quick Start

# Install
npm install -g feedbackbasket-cli

# Authenticate (opens browser, full access by default)
feedbackbasket login

# Or use a token directly (for CI/headless)
feedbackbasket login --token fb_cli_your_token_here

# Remote server flow: use when localhost browser callbacks cannot reach the CLI
feedbackbasket login --manual

# Start exploring
feedbackbasket projects list
feedbackbasket feedback list
feedbackbasket feedback create "Login button is broken" --project myapp --type bug
feedbackbasket bugs list --severity high

The first time you log in, a setup wizard walks you through selecting a default project and installing the Claude Code skill.

Agent Usage

Any AI agent with shell access (Claude Code, Codex, Cursor, OpenCode) can use the CLI directly:

# Agents should use --agent flag for raw JSON output
feedbackbasket projects list --agent
feedbackbasket feedback list --category BUG --agent
feedbackbasket feedback create "Login button is broken" --content "Clicking Log in does nothing in Safari." --project myapp --type bug --agent
feedbackbasket feedback update <id> --status PLANNED --agent
feedbackbasket widget script myproject --agent

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.

Install Claude Code Skill

feedbackbasket setup claude

Commands

Authentication

feedbackbasket login                   # Browser OAuth flow (alias for auth login)
feedbackbasket login --manual          # No localhost browser callback (remote servers)
feedbackbasket login --token <token>   # Use an existing CLI token (CI / scripts)
feedbackbasket logout                  # Clear credentials (alias for auth logout)
feedbackbasket auth status             # Show auth state, scope, default project
feedbackbasket auth token              # Print raw token (for scripting/piping)

CLI tokens start with fb_cli_. MCP API keys start with fb_key_ and are only for MCP server configuration.

Projects

All project commands accept name or ID (e.g. feedbackbasket or cmn3c7sgv...).

feedbackbasket projects list                              # List all projects with stats
feedbackbasket projects show <name-or-id>                 # Project details
feedbackbasket projects create "My App" --url https://... # Create project
feedbackbasket projects create "Local Test" --url http://localhost:3000 --allow-local-url
feedbackbasket projects update myapp --name "New Name"    # Update project
feedbackbasket projects update myapp --reply-to [email protected]  # Set default reply-to email
feedbackbasket projects delete myapp                      # Delete (with confirmation)

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.

Feedback

# Read
feedbackbasket feedback list                              # List recent feedback
feedbackbasket feedback list --project myapp              # Filter by project
feedbackbasket feedback list --category BUG               # Filter by category
feedbackbasket feedback list --status OPEN                # Filter by status
feedbackbasket feedback list --sentiment NEGATIVE          # Filter by sentiment
feedbackbasket feedback list --search "login issue"        # Text search
feedbackbasket feedback show <id>                          # View detail, including attachment links
feedbackbasket feedback search "crash on mobile"           # Search shortcut

# Write
feedbackbasket feedback create "Title" --content "Body" --project myapp
feedbackbasket feedback create "Login bug" --content "Clicking Log in does nothing" --project myapp --type bug --page-url https://example.com/login
feedbackbasket feedback update <id> --status PLANNED       # Update status
feedbackbasket feedback update <id> --category BUG         # Update category
feedbackbasket feedback reply <id> "Thanks!" --delivery email --reply-to [email protected]
feedbackbasket feedback reply <id> "Thanks!" --delivery widget
feedbackbasket feedback reply <id> "Thanks!" --delivery both --reply-to [email protected]
feedbackbasket feedback replies <id>                       # List sent replies
feedbackbasket feedback note <id> "Investigating this..."  # Add internal note
feedbackbasket feedback delete <id>                        # Delete feedback
feedbackbasket feedback bulk-update --status CLOSED --ids id1,id2,id3

# Export
feedbackbasket feedback export myapp --format csv          # Export to CSV
feedbackbasket feedback export myapp --format md           # Export to Markdown
feedbackbasket feedback export myapp --format json         # Export to JSON

Bug Reports

feedbackbasket bugs list                    # All bugs
feedbackbasket bugs list --severity high    # High severity only
feedbackbasket bugs list --status OPEN      # Open bugs
feedbackbasket bugs stats                   # Bug statistics summary
feedbackbasket bugs stats --project myapp   # Per-project stats

Widget

# View current settings
feedbackbasket widget settings myapp

# Update widget configuration
feedbackbasket widget settings myapp --color "#22c55e" --label "Send Feedback"
feedbackbasket widget settings myapp --position bottom-left --display modal
feedbackbasket widget settings myapp --email-required --intro "How can we improve?"
feedbackbasket widget settings myapp --button-radius 10 --button-size regular
feedbackbasket widget settings myapp --show-email --allow-attachments
feedbackbasket widget settings myapp --email-read-only --hide-email-when-prefilled

# Configure guided feedback types and follow-up questions
feedbackbasket widget flow myapp
feedbackbasket widget flow myapp --enable                  # guided only when requested
feedbackbasket widget flow myapp --reset-default --enable  # guided only when requested
feedbackbasket widget flow myapp --config ./feedback-flow.json

# Get embed code (ready to paste into your HTML)
feedbackbasket widget script myapp

For inline trigger mode, load the widget once and call the public API from your own button:

<button onclick="window.FeedbackWidget.openFeedbackForm({ trigger: event.currentTarget })">
  Feedback
</button>

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.

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.

The default widget experience is a basic modal. Only switch to popup mode or enable guided feedback when you intentionally want that flow.

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.

{
  "enabled": true,
  "mode": "guided",
  "types": [
    {
      "id": "bug",
      "emoji": "🐞",
      "label": "Bug report",
      "description": "Something is broken or not working",
      "questions": [
        {
          "id": "steps",
          "label": "What steps can reproduce it?",
          "type": "textarea"
        }
      ]
    }
  ]
}

Team

feedbackbasket team list                          # List organization members
feedbackbasket team role <memberId> --role admin   # Update member role
feedbackbasket team remove <memberId>              # Remove member

Utilities

feedbackbasket doctor         # Run diagnostics (auth, connectivity, integrations)
feedbackbasket setup claude   # Install Claude Code skill

Output Modes

The CLI automatically detects your environment:

| Context | Behavior | |---------|----------| | Terminal (TTY) | Styled, human-readable output with FeedbackBasket brand colors | | Piped | JSON output automatically | | --json | Full JSON envelope with breadcrumbs | | --quiet / --agent | Raw JSON data only (no envelope) | | --md | Markdown formatted |

JSON Envelope

{
  "ok": true,
  "data": [...],
  "summary": "12 open bugs, 3 high severity",
  "breadcrumbs": [
    { "action": "View high severity", "cmd": "feedbackbasket bugs list --severity high" }
  ]
}

Breadcrumbs suggest the next logical command — useful for both humans and agents navigating without a full command catalog.

Configuration

Credentials stored in ~/.config/feedbackbasket/credentials.json. Config in ~/.config/feedbackbasket/config.json.

Default Project

Set during the login wizard, or manually:

# Commands auto-scope to your default project
feedbackbasket feedback list        # uses default project
feedbackbasket feedback list --project other-app  # override

Environment Variables

| Variable | Description | |----------|-------------| | FEEDBACKBASKET_TOKEN | CLI token (bypasses stored credentials) | | FEEDBACKBASKET_BASE_URL | API base URL override |

Global Flags

| Flag | Description | |------|-------------| | --json | Full JSON envelope output | | --quiet / --agent | Raw JSON data only | | --md | Markdown output | | --base-url <url> | Override API base URL |

Filter Options

| Type | Values | |------|--------| | Categories | BUG, FEATURE_REQUEST, IMPROVEMENT, QUESTION | | Statuses | OPEN, UNDER_REVIEW, PLANNED, IN_PROGRESS, COMPLETE, CLOSED | | Sentiments | POSITIVE, NEGATIVE, NEUTRAL | | Bug Severity | high, medium, low |

Development

git clone https://github.com/deifos/feedbackbasket-cli.git
cd feedbackbasket-cli
npm install
npm run dev -- --help         # Run in development
npm run build                 # Build for production
npm run dev -- login          # Test login flow
npm run dev -- doctor         # Test diagnostics

License

MIT