> ## Documentation Index
> Fetch the complete documentation index at: https://octolens.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Filters, tags & feedback

> Cut noise with global filters and tags, and teach the relevance model with 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](/docs/cli/contract/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](/docs/cli/contract/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**

```bash theme={null}
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:

```json theme={null}
{
  "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](/docs/cli/contract/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**

```bash theme={null}
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:

```json theme={null}
{
  "totalFeedback": 24,
  "relevantCount": 18,
  "notRelevantCount": 6,
  "falsePositiveRate": 0.25
}
```

**Exit codes** — `0` OK · `1` UNEXPECTED · `2` USAGE. The full map is on [Exit codes](/docs/cli/contract/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**

```bash theme={null}
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:

```json theme={null}
{
  "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](/docs/cli/contract/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**

```bash theme={null}
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:

```json theme={null}
{
  "list": "negativeKeywords",
  "added": [
    "giveaway"
  ],
  "dropped": [],
  "values": [
    "scam",
    "@spambot",
    "giveaway"
  ]
}
```

**Exit codes** — `0` OK · `1` UNEXPECTED · `2` USAGE. The full map is on [Exit codes](/docs/cli/contract/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**

```bash theme={null}
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`).

<Accordion title="Example output">
  ```json theme={null}
  {
    "negativeKeywords": [
      "scam",
      "@spambot"
    ],
    "negativeAuthors": [
      "spambot1"
    ],
    "negativeSubreddits": [
      "unpopularopinion"
    ],
    "positiveSubreddits": [],
    "negativeRepos": [
      "acme/spam-repo"
    ]
  }
  ```
</Accordion>

**Exit codes** — `0` OK · `1` UNEXPECTED · `2` USAGE. The full map is on [Exit codes](/docs/cli/contract/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**

```bash theme={null}
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:

```json theme={null}
{
  "list": "negativeKeywords",
  "removed": [
    "scam"
  ],
  "values": [
    "@spambot",
    "giveaway"
  ]
}
```

**Exit codes** — `0` OK · `1` UNEXPECTED · `2` USAGE · `8` CANCELLED. The full map is on [Exit codes](/docs/cli/contract/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**

```bash theme={null}
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:

```json theme={null}
{
  "list": "negativeKeywords",
  "values": [
    "scam",
    "giveaway"
  ]
}
```

**Exit codes** — `0` OK · `1` UNEXPECTED · `2` USAGE · `8` CANCELLED. The full map is on [Exit codes](/docs/cli/contract/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**

```bash theme={null}
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:

```json theme={null}
{
  "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](/docs/cli/contract/exit-codes).