Filters, tags & feedback

Flags and arguments below are the contract as the binary states it. The global flags (--json, --timeout, …) apply here too and are documented on Global flags. Error codes are a workspace-global contract, not a per-command one — the taxonomy, and how to read a code that is not in it, is on The error envelope.

`octolens feedback rm`

Remove the relevance feedback on a mention Arguments

Argument	Type	Required	Description
`SOURCEID`	`string`	required	Mention id from a list/export row — the stable sourceId or the internal numeric id

Flags

Flag	Type	Required (headless)	Description
`--yes`	`boolean`	yes (headless)	Skip the confirmation prompt

Examples

octolens feedback rm reddit_t3_1abc234 --yes
octolens feedback rm reddit_t3_1abc234 --yes --json

Returns With --json, stdout carries one JSON document with these fields. Backed by the v2 API operation DELETE /api/v2/feedback.

Field	Type	Description
`ok`	boolean	Always `true` — removal of absent feedback is a harmless no-op, not an error.
`sourceId`	string	The mention whose feedback was targeted.
`removed`	boolean	`true` when a stored record was deleted; `false` when no feedback existed for that mention.

Without --json: A terminal prints one line saying whether anything was removed. Example output:

{
  "ok": true,
  "sourceId": "reddit_t3_1abc234",
  "removed": true
}

Exit codes — 0 OK · 1 UNEXPECTED · 2 USAGE · 8 CANCELLED. The full map is on Exit codes.

`octolens feedback stats`

Show aggregated relevance-feedback stats (org-wide or per-keyword) Flags

Flag	Type	Required (headless)	Description
`--keyword`	`integer`	no	Narrow the stats to one keyword id (omit for org-wide totals)

Examples

octolens feedback stats
octolens feedback stats --keyword 42 --json

Returns With --json, stdout carries one JSON document with these fields. Backed by the v2 API operation GET /api/v2/feedback/stats.

Field	Type	Description
`totalFeedback`	integer	Total feedback records (org-wide, or one keyword with `--keyword`).
`relevantCount`	integer	Records marked `RELEVANT`.
`notRelevantCount`	integer	Records marked `NOT_RELEVANT`.
`falsePositiveRate`	number	Fraction (0–1) of records marked `NOT_RELEVANT`. Higher = the AI over-reports. `0` with no feedback.

Without --json: A terminal renders the totals as an aligned table. Example output:

{
  "totalFeedback": 24,
  "relevantCount": 18,
  "notRelevantCount": 6,
  "falsePositiveRate": 0.25
}

Exit codes — 0 OK · 1 UNEXPECTED · 2 USAGE. The full map is on Exit codes.

`octolens feedback submit`

Submit relevance feedback on a mention (thumbs up/down) Arguments

Argument	Type	Required	Description
`SOURCEID`	`string`	required	Mention id from a list/export row — the stable sourceId or the internal numeric id

Flags

Flag	Type	Required (headless)	Description
`--keyword`	`integer`	no	Keyword id this feedback is about (defaults to the mention’s matched keyword)
`--not-relevant`	`boolean`	one of (headless)	Mark the mention NOT_RELEVANT (mutually exclusive with —relevant)
`--reason`	`string`	no	Optional free-text reason shown to the relevance agent
`--relevant`	`boolean`	one of (headless)	Mark the mention RELEVANT (mutually exclusive with —not-relevant)

Examples

octolens feedback submit reddit_t3_1abc234 --relevant
octolens feedback submit reddit_t3_1abc234 --not-relevant --reason 'off-topic'
octolens feedback submit reddit_t3_1abc234 --not-relevant --keyword 42 --json

Returns With --json, stdout carries one JSON document with these fields. Backed by the v2 API operation POST /api/v2/feedback.

Field	Type	Description
`ok`	boolean	Always `true` — a failed submit answers the error envelope instead.
`id`	integer	Id of the stored feedback record.
`sourceId`	string	The mention the feedback is about.
`keywordId`	integer	The keyword the mention matched.
`feedbackType`	enum: `RELEVANT`, `NOT_RELEVANT`	The committed verdict.
`feedbackReason`	string \| null	Free-text reason, when one was given.

Without --json: A terminal renders the stored feedback record. Example output:

{
  "ok": true,
  "id": 311,
  "sourceId": "reddit_t3_1abc234",
  "keywordId": 42,
  "feedbackType": "NOT_RELEVANT",
  "feedbackReason": "Job posting, not a product mention."
}

Exit codes — 0 OK · 1 UNEXPECTED · 2 USAGE. The full map is on Exit codes.

`octolens filters add`

Add value(s) to a global filter list (skips duplicates) Arguments

Argument	Type	Required	Description
`LIST`	`string`	required	Which list: negativeKeywords, negativeAuthors, negativeSubreddits, positiveSubreddits, negativeRepos
`VALUE`	`string`	optional	Value(s) to add — at least one required, space-separated

Examples

octolens filters add negativeKeywords porn scam
octolens filters add negativeAuthors spambot1 --json
octolens filters add negativeRepos acme/spam-repo

Returns With --json, stdout carries one JSON document with these fields. Backed by the v2 API operation POST /api/v2/filters/global/add.

Field	Type	Description
`list`	enum: `negativeKeywords`, `negativeAuthors`, `negativeSubreddits`, `positiveSubreddits`, `negativeRepos`	The list that was operated on.
`added`	string[]	Values that actually landed, in stored form — read back from the committed row.
`dropped`	string[]	Values refused because they already sit in the mutually-exclusive counterpart list. Values merely already present appear in neither array.
`values`	string[]	The full list after the change, as committed.

Without --json: A terminal confirms how many values were added and renders the list’s new contents. Example output:

{
  "list": "negativeKeywords",
  "added": [
    "giveaway"
  ],
  "dropped": [],
  "values": [
    "scam",
    "@spambot",
    "giveaway"
  ]
}

Exit codes — 0 OK · 1 UNEXPECTED · 2 USAGE. The full map is on Exit codes.

`octolens filters get`

Show your org-wide filter lists (all, or one with —list) Flags

Flag	Type	Required (headless)	Description
`--list`	`string`	no	Show only one list (negativeKeywords, negativeAuthors, negativeSubreddits, positiveSubreddits, negativeRepos)

Examples

octolens filters get
octolens filters get --list negativeKeywords
octolens filters get --json

Returns With --json, stdout carries one JSON document with these fields. Backed by the v2 API operation GET /api/v2/filters/global.

Field	Type	Description
`negativeKeywords`	string[]	Words, phrases, or `@handle` / `$TICKER` tokens that disqualify a mention org-wide.
`negativeAuthors`	string[]	Author handles filtered out org-wide (exact match against `mention.author`).
`negativeSubreddits`	string[]	Subreddits excluded from Reddit collection (stored without the `r/` prefix).
`positiveSubreddits`	string[]	Subreddit allowlist — when non-empty, Reddit mentions are restricted to these.
`negativeRepos`	string[]	GitHub repos excluded, in `owner/name` form.

Without --json: A terminal renders each list with its values (or just one list with --list).

Example output

{
  "negativeKeywords": [
    "scam",
    "@spambot"
  ],
  "negativeAuthors": [
    "spambot1"
  ],
  "negativeSubreddits": [
    "unpopularopinion"
  ],
  "positiveSubreddits": [],
  "negativeRepos": [
    "acme/spam-repo"
  ]
}

Exit codes — 0 OK · 1 UNEXPECTED · 2 USAGE. The full map is on Exit codes.

`octolens filters remove`

Remove value(s) from a global filter list Arguments

Argument	Type	Required	Description
`LIST`	`string`	required	Which list: negativeKeywords, negativeAuthors, negativeSubreddits, positiveSubreddits, negativeRepos
`VALUE`	`string`	optional	Value(s) to remove — at least one required, space-separated

Flags

Flag	Type	Required (headless)	Description
`--yes`	`boolean`	no	Confirm a removal that would EMPTY the list (not needed while values remain)

Examples

octolens filters remove negativeKeywords scam
octolens filters remove negativeAuthors spambot1 --json
octolens filters remove negativeKeywords scam --yes

Returns With --json, stdout carries one JSON document with these fields. Backed by the v2 API operation POST /api/v2/filters/global/remove.

Field	Type	Description
`list`	enum: `negativeKeywords`, `negativeAuthors`, `negativeSubreddits`, `positiveSubreddits`, `negativeRepos`	The list that was operated on.
`removed`	string[]	Entries that left the list, exactly as they were stored. Values not present are ignored.
`values`	string[]	The full list after the change, as committed.

Without --json: A terminal confirms how many values were removed and renders the list’s new contents. Example output:

{
  "list": "negativeKeywords",
  "removed": [
    "scam"
  ],
  "values": [
    "@spambot",
    "giveaway"
  ]
}

Exit codes — 0 OK · 1 UNEXPECTED · 2 USAGE · 8 CANCELLED. The full map is on Exit codes.

`octolens filters set`

Replace a global filter list wholesale (no values + —clear = empty it) Arguments

Argument	Type	Required	Description
`LIST`	`string`	required	Which list: negativeKeywords, negativeAuthors, negativeSubreddits, positiveSubreddits, negativeRepos
`VALUE`	`string`	optional	The replacement value(s) — omit (with —clear) to empty the list

Flags

Flag	Type	Required (headless)	Description
`--clear`	`boolean`	no	Confirm emptying the list (required to clear a non-empty list headlessly)
`--values-json`	`string`	no	The replacement values as a JSON array of strings (alternative to positional values)

Examples

octolens filters set negativeKeywords porn scam spam
octolens filters set positiveSubreddits nextjs vercel --json
octolens filters set negativeKeywords --clear
octolens filters set negativeKeywords --values-json '["a b","c,d"]'

Returns With --json, stdout carries one JSON document with these fields. Backed by the v2 API operation PATCH /api/v2/filters/global.

Field	Type	Description
`list`	enum: `negativeKeywords`, `negativeAuthors`, `negativeSubreddits`, `positiveSubreddits`, `negativeRepos`	The list that was replaced.
`values`	string[]	The full list after the replacement, as committed.

Without --json: A terminal confirms the replacement and renders the list’s new contents. Example output:

{
  "list": "negativeKeywords",
  "values": [
    "scam",
    "giveaway"
  ]
}

Exit codes — 0 OK · 1 UNEXPECTED · 2 USAGE · 8 CANCELLED. The full map is on Exit codes.

`octolens tags list`

List the AI-assigned tag names on your mentions — filter mentions by tag via feeds create —filter-json (a Tags condition) Flags

Flag	Type	Required (headless)	Description
`--all`	`boolean`	no	Show the full collection (the default for this bounded list)
`--limit`	`integer`	no	Show only the first N items (mutually exclusive with —all)

Examples

octolens tags list
octolens tags list --json
octolens tags list --limit 10

Returns With --json, stdout carries one JSON document with these fields. Backed by the v2 API operation GET /api/v2/tags.

Field	Type	Description
`data`	string[]	Tag names usable with `mentions list --tag`: the union of tags seen on this org’s mentions and the conventional common set, deduped and sorted.
`pagination.nextCursor`	null	Always `null`: the whole tag set fits one response.

Without --json: A terminal renders an indented tag list; piped stdout emits one bare tag per line. Example output:

{
  "data": [
    "bug_report",
    "buy_intent",
    "competitor_mention",
    "pricing"
  ],
  "pagination": {
    "nextCursor": null
  }
}

Exit codes — 0 OK · 1 UNEXPECTED · 2 USAGE. The full map is on Exit codes.

Get started

Contract

Commands

Concepts

Guides

Scripting & agents

Filters, tags & feedback

`octolens feedback rm`

`octolens feedback stats`

`octolens feedback submit`

`octolens filters add`

`octolens filters get`

`octolens filters remove`

`octolens filters set`

`octolens tags list`

​octolens feedback rm

​octolens feedback stats

​octolens feedback submit

​octolens filters add

​octolens filters get

​octolens filters remove

​octolens filters set

​octolens tags list

`octolens feedback rm`

`octolens feedback stats`

`octolens feedback submit`

`octolens filters add`

`octolens filters get`

`octolens filters remove`

`octolens filters set`

`octolens tags list`