How to Use the Feedback Command in Context Hub: A Complete CLI Guide

The feedback command in Context Hub lets you rate documentation entries and skills with up/down votes, attach structured labels, and transmit feedback to registry maintainers via an HTTP POST to the telemetry endpoint.

Context Hub is an open-source CLI tool for managing and discovering AI context resources. The feedback command provides a direct channel to registry maintainers, allowing you to submit ratings and annotations that improve the quality of curated docs and skills according to the andrewyng/context-hub source code.

Command Syntax and Basic Usage

The chub feedback command requires an entry ID and a rating value. According to cli/src/commands/feedback.js (lines 66-73), the syntax validates that both <id> and <rating> are present and that the rating is either up or down.

chub feedback <id> <rating> [comment] [options]

Available options include:

• --type - Explicitly set entry type (doc or skill)
• --lang - Specify document language
• --file - Target a specific file within the entry
• --label - Add structured tags (repeatable)
• --agent - Identify the AI agent generating feedback
• --model - Specify the model version
• --status - Display current feedback configuration

How the Feedback Command Works Internally

When you execute chub feedback, the CLI orchestrates several subsystems across the codebase to validate, enrich, and transmit your input.

CLI Parsing and Argument Validation

The command entry point in cli/src/commands/feedback.js registers the command with chub feedback [id] [rating]. The parser collects repeated --label values into an array, normalizes them against the VALID_LABELS whitelist (lines 13-17), and attaches the current CLI version from package.json (lines 18-23). If required arguments are missing or the rating is invalid, the process exits with an error before reaching the telemetry layer.

Feature Gating and Configuration

Before transmitting data, the command invokes isFeedbackEnabled() from cli/src/lib/telemetry.js. This function checks ~/.chub/config.yaml for feedback: true (the default) and respects the CHUB_FEEDBACK environment variable. If disabled, the command exits early with a skipped status. When you pass --status, the CLI calls loadConfig() from cli/src/lib/config.js to display the client ID prefix, telemetry endpoint URL, and enabled status.

Entry Resolution and Type Detection

The command uses getEntry(id) from cli/src/lib/registry.js to load metadata from the local cache. If --type is omitted, the code infers whether the entry is a doc or skill by checking for the presence of a languages array (lines 84-95). For single-language documents, the --lang and --doc-version fields auto-populate from the registry metadata (lines 98-104).

Payload Construction and Transmission

The sendFeedback() function in cli/src/lib/telemetry.js (lines 25-41) constructs a JSON payload containing:

• Entry identifiers (entry_id, entry_type)
• Rating value (up or down)
• Optional metadata (language, version, target file, labels, comment)
• Agent context (name, model, detected version)
• CLI version and registry source
• Client ID header from getOrCreateClientId()

The function POSTs this data to <telemetry_url>/feedback, defaulting to https://api.aichub.org/v1/feedback as defined by DEFAULT_TELEMETRY_URL on line 3. A 3-second timeout aborts unresponsive requests. Upon success, the CLI prints a confirmation and trackEvent('feedback_sent', ...) in cli/src/lib/analytics.js logs the interaction for usage analytics.

Configuration and Disabling Feedback

You can disable feedback collection persistently by setting feedback: false in ~/.chub/config.yaml, or temporarily by exporting CHUB_FEEDBACK=0 before running the command. These settings are documented in docs/cli-reference.md and docs/feedback-and-annotations.md.

Practical Usage Examples

Here are concrete examples demonstrating the feedback command's capabilities:

# Basic up-vote with comment

chub feedback stripe/api up "Clear examples, well-structured"

# Down-vote with multiple labels

chub feedback openai/chat down \
  --label outdated \
  --label wrong-examples \
  "Examples don't match the latest API"

# Target a specific reference file

chub feedback acme/widgets down \
  --file references/advanced.md \
  --label incomplete \
  "Missing step-by-step guide"

# Include agent metadata for maintainer context

chub feedback stripe/api up \
  --agent "claude-code" \
  --model "claude-sonnet-4" \
  "Code snippets work perfectly with Claude"

# Check current feedback status

chub feedback --status

# Temporarily disable feedback for one command

CHUB_FEEDBACK=0 chub feedback stripe/api up

Example JSON payload structure sent to the server (lines 25-41 in telemetry.js):

{
  "entry_id": "stripe/api",
  "entry_type": "doc",
  "rating": "up",
  "doc_lang": "js",
  "doc_version": "2023-08",
  "target_file": "references/webhooks.md",
  "labels": ["accurate", "helpful"],
  "comment": "Great examples, very clear",
  "agent": {
    "name": "claude-code",
    "version": "1.2.0",
    "model": "claude-sonnet-4"
  },
  "cli_version": "2.5.1",
  "source": "official"
}

Summary

• The feedback command wraps the telemetry subsystem to POST ratings to https://api.aichub.org/v1/feedback with a 3-second timeout.
• Implementation resides in cli/src/commands/feedback.js, with core logic in cli/src/lib/telemetry.js.
• Ratings must be up or down; optional labels are validated against VALID_LABELS.
• Entry type auto-detection occurs in cli/src/lib/registry.js based on metadata structure.
• Disable feedback via ~/.chub/config.yaml (feedback: false) or the CHUB_FEEDBACK environment variable.

Frequently Asked Questions

What happens if I submit feedback while offline?

If the POST request to the telemetry endpoint fails or times out after 3 seconds, the CLI displays a red error message but does not queue the feedback for retry. The feedback is recorded only upon successful server acknowledgment as implemented in cli/src/lib/telemetry.js.

Can I use custom labels when submitting feedback?

No. Labels are normalized and filtered against a whitelist defined in cli/src/commands/feedback.js (lines 13-17). Only valid labels from VALID_LABELS are included in the payload; invalid entries are silently discarded during the collection phase.

How does Context Hub detect whether I'm rating a doc or a skill?

If you omit the --type flag, the command calls getEntry() from cli/src/lib/registry.js and infers the type by checking for a languages array in the metadata (lines 84-95). Docs typically specify supported languages, while skills do not, allowing automatic classification.

Is my feedback anonymous?

The CLI includes a client ID generated by getOrCreateClientId() in the request headers to prevent duplicate submissions, but this identifier is not tied to personal authentication. The payload contains no user credentials, only the CLI version, entry metadata, and your rating content.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}