StarReview agent CLI

draft and submit review replies for local businesses. you draft and submit; the owner approves; starreview publishes. you cannot post replies yourself (no command exists for it).

intent

use this skill when managing a business's online review presence across multiple platforms (google, tripadvisor, etc). you list unanswered reviews, generate reply drafts in the owner's voice, submit them for the owner's explicit approval, and track review metrics. the owner always controls publishing. starreview handles the actual post via their API or sends you a manual post link for platforms without APIs.

inputs

starreview CLI

• install: npm install -g @starreview/cli or use npx @starreview/cli <command>
• env var: STARREVIEW_API_KEY=sragt_... (owner creates this in starreview.ch settings under Einstellungen -> Agent-Zugang)
• key scope: covers ALL businesses the owner manages
• note: info and check commands work without a key; use check to show the owner their current response rate before they sign up

rate limits and quotas

• 20 calls/minute per key
• 10 calls/minute per IP (public endpoints)
• ~25 draft calls/day per business
• check results cached ~30 days (do not repeat for the same location)

external connection: starreview API

• endpoint: https://www.starreview.ch/ (production)
• auth: bearer token via STARREVIEW_API_KEY
• response format: one JSON document per command to stdout
• error response: { "error": "<code>", "message": "..." } with non-zero exit code
• compatibility: additive-only changes (new fields, commands, provider values) in minor versions; nothing existing is removed or changes meaning without a MAJOR version bump

procedure

1. list review stats (optional)

   • input: days window (e.g. 30)
   • command: starreview stats --days 30
   • output: json object with review counts, response rate, sentiment breakdown
   • use case: show owner their performance before diving into drafts

2. fetch unanswered reviews

   • input: limit (1-50, default 10), optional business id, location id, provider filter
   • command: starreview reviews --limit 10 [--business <id>] [--location <id>] [--provider <slug>]
   • output: json array of review objects, each with reviewId, provider, rating, text, createdAt
   • edge case: if response contains businesses + hint fields, you have a multi-business picker (see decision points); re-run with --business <id>
   • edge case: empty result set is normal (all reviews answered or no reviews); do not error

3. retrieve full review details

   • input: reviewId (from step 2)
   • command: starreview review <reviewId>
   • output: json object with full text, detected language, any existing drafts, sentiment analysis, platform-specific fields
   • use case: before drafting, check the full context and any prior work

4. generate reply draft(s)

   • input: reviewId, owner's voice/tone (implicit in starreview's model)
   • command: starreview draft <reviewId>
   • output: json object with variants array (typically 2-3 reply options), each with variantId, text, sentiment analysis
   • cost: free; owner only pays when a reply is published (CHF 0.50)
   • note: sentiment check always runs; negative and sensitive reviews always route to owner approval (never auto-post)
   • edge case: if owner has exhausted daily draft cap, error daily_draft_cap_exceeded - stop for the day

5. submit reply for approval

   • input: reviewId, chosen variantId OR custom text, optional post-at timestamp
   • command: starreview submit <reviewId> --variant <n> OR starreview submit <reviewId> --text "..." OR starreview submit <reviewId> --variant <n> --text "..." [--post-at ]
   • output: json object with submitted: true, autoScheduled: true (if auto-posting on standing consent), or awaitingManualPost: true + platformListingUrl (manual platforms)
   • post-at behavior: if provided, starreview delays posting until that timestamp
   • custom text: always waits for owner approval (does not auto-schedule)
   • edge case: platform without reply API (e.g. tripadvisor) returns awaitingManualPost: true + platformListingUrl - this is success, not failure; owner posts via the link
   • edge case: already_processed error means reply was already submitted; treat as success (idempotent)

6. interpret post-submit outcome

   • input: submit response json
   • branches:
     • if autoScheduled: true: starreview is posting the reply automatically (unedited draft, positive review, owner has standing consent); tell owner it will post at scheduled time
     • if submitted: true (no scheduling): reply is in owner's approval queue; owner must review and approve in starreview UI before posting
     • if awaitingManualPost: true: platform has no API (e.g. tripadvisor); owner must post via the platformListingUrl provided; this is not a system failure
   • output: human-readable status message

decision points

multi-business handling

• if response contains businesses (array of objects with businessId, name) + hint field, the owner manages multiple businesses
• action: do NOT treat this as the answer; display the picker to the owner, then re-run the command with --business <businessId>
• note: review-keyed commands (review, draft, submit) never return a picker (the review pins the business)

api key present?

• if STARREVIEW_API_KEY is set and valid: proceed with authenticated commands (draft, submit, stats, full reviews list)
• else if STARREVIEW_API_KEY is missing or invalid: error missing_api_key or unauthorized; check env var, regenerate key in starreview.ch settings
• note: info and check commands work without a key (useful for pre-signup diagnostics)

platform-specific post outcome

• if autoScheduled: true: reply posts automatically; only inform, do not ask for additional action
• if submitted: true (no auto-scheduling): reply waits in owner's queue; ask owner to review and approve in starreview UI
• if awaitingManualPost: true: platform has no reply API; display platformListingUrl and ask owner to post manually via that link
• never claim a reply "was posted" unless autoScheduled: true; always say "submitted for approval" otherwise

error classification

• refusals (do NOT retry blindly):
  • forbidden, posting_paywall (owner must subscribe), review_not_pending (refresh the list), free_quota_exhausted, not_editable, business_not_connected (send owner to onboarding)
  • action: inform owner of the issue and next steps; do not retry
• auth/config errors (fix and retry once):
  • missing_api_key, unauthorized (regenerate key)
  • action: check env var, regenerate key in starreview.ch, retry
• transient/limit errors (backoff and retry):
  • rate_limited_per_minute (back off 60+ seconds), db_error, internal_error, network_error
  • action: wait and retry with exponential backoff
• invalid input (do not retry):
  • invalid_arguments, not_found, variant_not_found (re-run draft), daily_draft_cap_exceeded (stop for the day)
  • action: fix the input or wait, then retry

draft cap exhausted

• if error daily_draft_cap_exceeded: the owner has hit ~25 drafts/day for this business
• action: inform owner, stop drafting until the next calendar day

platform growth

• provider field values (e.g. google, tripadvisor) grow as starreview adds platforms
• action: never hardcode or reject unknown provider values; parse and handle them gracefully
• what differs per platform: only the post-submit outcome (auto-scheduled, pending approval, or manual post); response always signals which via json fields

output contract

all commands output exactly one JSON document to stdout. parse it as follows:

success response

• structure: { "data": <payload>, ... } or direct payload (varies by command)
• for reviews: array of review objects with reviewId, provider, rating, text, createdAt, businessId, location
• for review: single review object with fullText, language, sentiment, provider, existingDrafts (if any), platform-specific fields
• for draft: object with variants array, each containing variantId, text, sentiment
• for submit: object with submitted: true, optionally autoScheduled: true or awaitingManualPost: true + platformListingUrl, postId (if auto-posted), scheduledAt (if delayed)
• for stats: object with reviewCount, responseRate, avgRating, sentimentBreakdown (counts by sentiment)
• for check: object with business name, location, response rate, review count (cached ~30 days)

error response

• structure: { "error": "<code>", "message": "<human-readable text>" }
• exit code: non-zero on any error (use this to branch on success/failure)
• do NOT assume error codes are exhaustive; log the full response for debugging

no response / timeout

• if command hangs >30s or returns nothing: network issue or service outage
• action: retry with backoff; if persistent, check starreview.ch status page

outcome signal

the user (owner) knows the skill worked when:

1. review list displayed: you show a list of unanswered reviews with counts and providers (e.g. "3 google, 2 tripadvisor")

2. draft(s) generated: you display 2-3 reply variants in the owner's voice, each labeled with sentiment and the variantId

3. reply submitted: after submit succeeds:

   • if autoScheduled: true: message "your reply will post automatically on [date]"
   • if submitted: true: message "reply submitted to your approval queue; review it in starreview"
   • if awaitingManualPost: true: message "reply ready; post it here: [platformListingUrl]"

4. no false claims: you never say "posted" unless autoScheduled: true; you always distinguish between "submitted for approval" and "auto-posted"

5. error handling transparent: on refusal errors (e.g. posting_paywall), you explain what the owner must do (subscribe, reconnect platform, etc.) without retrying blindly

6. multi-business flows work: if the owner manages multiple businesses, you show the picker and re-run with the chosen business id without error

7. rate limits respected: if you hit 20 calls/min, you wait 60+ seconds before the next batch and inform the owner of the pause

original author: starreview team at clawhub