Troubleshoot the CLI

Start with the installed version, selected identity, repository config, and credential-safe diagnostics:

gleanfeed --version
gleanfeed whoami
gleanfeed config validate
gleanfeed agent status
gleanfeed feedback list --limit 1 --debug --json

--debug writes to stderr, so structured stdout remains parseable.

Authentication failed (exit 3)

The OAuth grant or API key is missing, expired, invalid, or revoked. Re-authenticate in the browser, then validate:

gleanfeed auth login --profile NAME
gleanfeed auth status --profile NAME

For CI, replace a revoked API key in Settings → API Keys and update the secret manager. Do not reuse a credential copied from a log or chat.

Authorization failed (exit 4)

The credential is valid but lacks the required scope or role. Compare the command with the scope table, then sign in again or create a narrowly scoped API key. --yes, --json, and --agent never grant access.

Resource not found (exit 5)

Confirm the resource ID and selected workspace with whoami. The API returns the same not-found response for a missing resource and a resource in another workspace, so it never leaks cross-workspace existence.

Repository binding mismatch

The selected profile’s workspace differs from .gleanfeed.json.

gleanfeed profile list
gleanfeed config get
gleanfeed init --profile EXPECTED_PROFILE
gleanfeed config validate

Do not manually change only workspaceId; it is derived and read-only. Select the correct authenticated profile and rerun init.

Invalid or unsupported config

Version 1 is the current schema. Back up an unversioned or older file and rerun gleanfeed init. If the file declares a future version, update the CLI instead of guessing a migration.

Board is required

Feedback creation needs an explicit board slug or UUID unless the repository has defaultBoard:

gleanfeed feedback create --board product-ideas --title "Request title"
gleanfeed config set defaultBoard product-ideas

Rate limited (exit 6)

Wait before retrying and honor the API’s retry interval. Keep list pages small, reuse idempotency keys for retried creates, and avoid parallel retry storms.

Remote service failure (exit 7)

Check network access to https://app.gleanfeed.com, then retry the same idempotent read. GitHub imports can return partial success with continuation.retryArgs; retry only those failed issue numbers.

Agent configuration exists but MCP is disconnected

agent install writes only the endpoint. Complete OAuth in the client:

Codex: codex mcp login glean-feed
Claude Code: /mcp, then select glean-feed
Cursor: Cursor Settings → MCP
VS Code: MCP: List Servers, then start glean-feed

Organization policy can prevent a client from adding or starting remote MCP servers. Review Agents and CI and the MCP guide before editing client files manually.

A write will not run in JSON or CI

Customer-visible and external writes require confirmation. Noninteractive callers must add --yes to the specific reviewed command. The CLI still applies authentication, scopes, workspace isolation, input validation, and idempotency. If the problem persists, send support the CLI version, command name, exit code, and redacted debug output. Never send a token, API key, or raw credential store.

​Authentication failed (exit 3)

​Authorization failed (exit 4)

​Resource not found (exit 5)

​Repository binding mismatch

​Invalid or unsupported config

​Board is required

​Rate limited (exit 6)

​Remote service failure (exit 7)

​Agent configuration exists but MCP is disconnected

​A write will not run in JSON or CI