# Topics commands

Signatures, flags and examples for recala topics.

## Use these commands

The topic queue: what Recala proposes to write next.

Examples assume you have signed in and selected the intended organization. Set shell variables such as `ARTICLE_ID` to ids from the corresponding list command. Set `PUBLICATION_TIME` to a future local time in YYYY-MM-DDTHH:MM format.

Badges describe the command’s strongest effect; a preview or read-only option may do less. [Guarded writes can require confirmation even without --yes](https://recala.co/developers/agents/#guarded). “Needs a person” covers identity, consent and credentials.

### [`recala topics add`](https://recala.co/developers/cli/topics/#cmd-topics-add)

Add your own topic (a buyer question) to the top of Up next.

writes Acts on an organization

```
recala topics add TOPIC [OPTIONS]
```

Replace uppercase arguments with your own values. Replace [OPTIONS] with the flags you need, or omit it.

| Flag | Required | Description |
| --- | --- | --- |
| `--json` | No | Print one JSON document (errors as JSON on stderr). |
| `--org` | No | Organization name, slug or id (else RECALA_ORG, else recala org use). |

#### Examples

Add your own buyer question to the top of Up next.

```
recala topics add "How do I choose a project tool for a small team?"
```

**Exit codes:** [`0` OK](https://recala.co/developers/reference/#exit-0), [`1` ERROR](https://recala.co/developers/reference/#exit-1), [`2` USAGE](https://recala.co/developers/reference/#exit-2), [`3` NOT_AUTHENTICATED](https://recala.co/developers/reference/#exit-3), [`4` FORBIDDEN](https://recala.co/developers/reference/#exit-4), [`5` NOT_FOUND](https://recala.co/developers/reference/#exit-5), [`6` CONFLICT](https://recala.co/developers/reference/#exit-6), [`7` INVALID](https://recala.co/developers/reference/#exit-7), [`8` RATE_LIMITED](https://recala.co/developers/reference/#exit-8), [`9` UNAVAILABLE](https://recala.co/developers/reference/#exit-9), [`10` CONFIRMATION_REQUIRED](https://recala.co/developers/reference/#exit-10), [`11` PAYMENT_REQUIRED](https://recala.co/developers/reference/#exit-11).

API commands share the CLI’s HTTP error mapping. [Read human and JSON output rules](https://recala.co/developers/reference/#json-output).

### [`recala topics approve`](https://recala.co/developers/cli/topics/#cmd-topics-approve)

Keep a proposed topic.

writes Acts on an organization

```
recala topics approve TOPIC_ID [OPTIONS]
```

Replace uppercase arguments with your own values. Replace [OPTIONS] with the flags you need, or omit it.

| Flag | Required | Description |
| --- | --- | --- |
| `--json` | No | Print one JSON document (errors as JSON on stderr). |
| `--org` | No | Organization name, slug or id (else RECALA_ORG, else recala org use). |

#### Examples

Keep a proposed topic.

```
recala topics approve "$TOPIC_ID"
```

**Exit codes:** [`0` OK](https://recala.co/developers/reference/#exit-0), [`1` ERROR](https://recala.co/developers/reference/#exit-1), [`2` USAGE](https://recala.co/developers/reference/#exit-2), [`3` NOT_AUTHENTICATED](https://recala.co/developers/reference/#exit-3), [`4` FORBIDDEN](https://recala.co/developers/reference/#exit-4), [`5` NOT_FOUND](https://recala.co/developers/reference/#exit-5), [`6` CONFLICT](https://recala.co/developers/reference/#exit-6), [`7` INVALID](https://recala.co/developers/reference/#exit-7), [`8` RATE_LIMITED](https://recala.co/developers/reference/#exit-8), [`9` UNAVAILABLE](https://recala.co/developers/reference/#exit-9), [`10` CONFIRMATION_REQUIRED](https://recala.co/developers/reference/#exit-10), [`11` PAYMENT_REQUIRED](https://recala.co/developers/reference/#exit-11).

API commands share the CLI’s HTTP error mapping. [Read human and JSON output rules](https://recala.co/developers/reference/#json-output).

### [`recala topics dismiss`](https://recala.co/developers/cli/topics/#cmd-topics-dismiss)

Drop a proposed topic from the queue.

writes Acts on an organization

```
recala topics dismiss TOPIC_ID [OPTIONS]
```

Replace uppercase arguments with your own values. Replace [OPTIONS] with the flags you need, or omit it.

| Flag | Required | Description |
| --- | --- | --- |
| `--json` | No | Print one JSON document (errors as JSON on stderr). |
| `--org` | No | Organization name, slug or id (else RECALA_ORG, else recala org use). |

#### Examples

Drop one you do not want.

```
recala topics dismiss "$TOPIC_ID"
```

**Exit codes:** [`0` OK](https://recala.co/developers/reference/#exit-0), [`1` ERROR](https://recala.co/developers/reference/#exit-1), [`2` USAGE](https://recala.co/developers/reference/#exit-2), [`3` NOT_AUTHENTICATED](https://recala.co/developers/reference/#exit-3), [`4` FORBIDDEN](https://recala.co/developers/reference/#exit-4), [`5` NOT_FOUND](https://recala.co/developers/reference/#exit-5), [`6` CONFLICT](https://recala.co/developers/reference/#exit-6), [`7` INVALID](https://recala.co/developers/reference/#exit-7), [`8` RATE_LIMITED](https://recala.co/developers/reference/#exit-8), [`9` UNAVAILABLE](https://recala.co/developers/reference/#exit-9), [`10` CONFIRMATION_REQUIRED](https://recala.co/developers/reference/#exit-10), [`11` PAYMENT_REQUIRED](https://recala.co/developers/reference/#exit-11).

API commands share the CLI’s HTTP error mapping. [Read human and JSON output rules](https://recala.co/developers/reference/#json-output).

### [`recala topics list`](https://recala.co/developers/cli/topics/#cmd-topics-list)

List the topic queue by section (up next, backlog, queued, processing, other).

read Acts on an organization

```
recala topics list [OPTIONS]
```

Replace [OPTIONS] with the flags you need, or omit it.

| Flag | Required | Description |
| --- | --- | --- |
| `--json` | No | Print one JSON document (errors as JSON on stderr). |
| `--org` | No | Organization name, slug or id (else RECALA_ORG, else recala org use). |
| `--section` | No | Only this section of the queue. |
| `--limit` | No | Fetch one page of this size; default: every visible topic. |
| `--offset` | No | No description supplied by the CLI. |

#### Examples

See what Recala proposes to write next.

```
recala topics list --section up_next
```

**Exit codes:** [`0` OK](https://recala.co/developers/reference/#exit-0), [`1` ERROR](https://recala.co/developers/reference/#exit-1), [`2` USAGE](https://recala.co/developers/reference/#exit-2), [`3` NOT_AUTHENTICATED](https://recala.co/developers/reference/#exit-3), [`4` FORBIDDEN](https://recala.co/developers/reference/#exit-4), [`5` NOT_FOUND](https://recala.co/developers/reference/#exit-5), [`6` CONFLICT](https://recala.co/developers/reference/#exit-6), [`7` INVALID](https://recala.co/developers/reference/#exit-7), [`8` RATE_LIMITED](https://recala.co/developers/reference/#exit-8), [`9` UNAVAILABLE](https://recala.co/developers/reference/#exit-9), [`11` PAYMENT_REQUIRED](https://recala.co/developers/reference/#exit-11).

API commands share the CLI’s HTTP error mapping. [Read human and JSON output rules](https://recala.co/developers/reference/#json-output).

### [`recala topics scout`](https://recala.co/developers/cli/topics/#cmd-topics-scout)

Find topics through the existing background scout, with the server's payment and entity gates.

writes Acts on an organization

```
recala topics scout [OPTIONS]
```

Replace [OPTIONS] with the flags you need, or omit it.

| Flag | Required | Description |
| --- | --- | --- |
| `--json` | No | Print one JSON document (errors as JSON on stderr). |
| `--org` | No | Organization name, slug or id (else RECALA_ORG, else recala org use). |

#### Examples

Set the named shell variables to your own values before running.

```
recala topics scout
```

**Exit codes:** [`0` OK](https://recala.co/developers/reference/#exit-0), [`1` ERROR](https://recala.co/developers/reference/#exit-1), [`2` USAGE](https://recala.co/developers/reference/#exit-2), [`3` NOT_AUTHENTICATED](https://recala.co/developers/reference/#exit-3), [`4` FORBIDDEN](https://recala.co/developers/reference/#exit-4), [`5` NOT_FOUND](https://recala.co/developers/reference/#exit-5), [`6` CONFLICT](https://recala.co/developers/reference/#exit-6), [`7` INVALID](https://recala.co/developers/reference/#exit-7), [`8` RATE_LIMITED](https://recala.co/developers/reference/#exit-8), [`9` UNAVAILABLE](https://recala.co/developers/reference/#exit-9), [`10` CONFIRMATION_REQUIRED](https://recala.co/developers/reference/#exit-10), [`11` PAYMENT_REQUIRED](https://recala.co/developers/reference/#exit-11).

API commands share the CLI’s HTTP error mapping. [Read human and JSON output rules](https://recala.co/developers/reference/#json-output).

### [`recala topics up-next add`](https://recala.co/developers/cli/topics/#cmd-topics-up-next-add)

Add an existing topic by id or exact title to Up next.

writes Acts on an organization

```
recala topics up-next add TOPIC [OPTIONS]
```

Replace uppercase arguments with your own values. Replace [OPTIONS] with the flags you need, or omit it.

| Flag | Required | Description |
| --- | --- | --- |
| `--json` | No | Print one JSON document (errors as JSON on stderr). |
| `--org` | No | Organization name, slug or id (else RECALA_ORG, else recala org use). |

#### Examples

Set the named shell variables to your own values before running.

```
recala topics up-next add "$TOPIC"
```

**Exit codes:** [`0` OK](https://recala.co/developers/reference/#exit-0), [`1` ERROR](https://recala.co/developers/reference/#exit-1), [`2` USAGE](https://recala.co/developers/reference/#exit-2), [`3` NOT_AUTHENTICATED](https://recala.co/developers/reference/#exit-3), [`4` FORBIDDEN](https://recala.co/developers/reference/#exit-4), [`5` NOT_FOUND](https://recala.co/developers/reference/#exit-5), [`6` CONFLICT](https://recala.co/developers/reference/#exit-6), [`7` INVALID](https://recala.co/developers/reference/#exit-7), [`8` RATE_LIMITED](https://recala.co/developers/reference/#exit-8), [`9` UNAVAILABLE](https://recala.co/developers/reference/#exit-9), [`10` CONFIRMATION_REQUIRED](https://recala.co/developers/reference/#exit-10), [`11` PAYMENT_REQUIRED](https://recala.co/developers/reference/#exit-11).

API commands share the CLI’s HTTP error mapping. [Read human and JSON output rules](https://recala.co/developers/reference/#json-output).

### [`recala topics up-next list`](https://recala.co/developers/cli/topics/#cmd-topics-up-next-list)

List the ordered topics in Up next.

read Acts on an organization

```
recala topics up-next list [OPTIONS]
```

Replace [OPTIONS] with the flags you need, or omit it.

| Flag | Required | Description |
| --- | --- | --- |
| `--json` | No | Print one JSON document (errors as JSON on stderr). |
| `--org` | No | Organization name, slug or id (else RECALA_ORG, else recala org use). |

#### Examples

Set the named shell variables to your own values before running.

```
recala topics up-next list
```

**Exit codes:** [`0` OK](https://recala.co/developers/reference/#exit-0), [`1` ERROR](https://recala.co/developers/reference/#exit-1), [`2` USAGE](https://recala.co/developers/reference/#exit-2), [`3` NOT_AUTHENTICATED](https://recala.co/developers/reference/#exit-3), [`4` FORBIDDEN](https://recala.co/developers/reference/#exit-4), [`5` NOT_FOUND](https://recala.co/developers/reference/#exit-5), [`6` CONFLICT](https://recala.co/developers/reference/#exit-6), [`7` INVALID](https://recala.co/developers/reference/#exit-7), [`8` RATE_LIMITED](https://recala.co/developers/reference/#exit-8), [`9` UNAVAILABLE](https://recala.co/developers/reference/#exit-9), [`11` PAYMENT_REQUIRED](https://recala.co/developers/reference/#exit-11).

API commands share the CLI’s HTTP error mapping. [Read human and JSON output rules](https://recala.co/developers/reference/#json-output).

### [`recala topics up-next move`](https://recala.co/developers/cli/topics/#cmd-topics-up-next-move)

Move a topic within the existing Up next order.

writes Acts on an organization

```
recala topics up-next move TOPIC [OPTIONS]
```

Replace uppercase arguments with your own values. Replace [OPTIONS] with your flags. Include every flag marked Required in the table below.

| Flag | Required | Description |
| --- | --- | --- |
| `--json` | No | Print one JSON document (errors as JSON on stderr). |
| `--org` | No | Organization name, slug or id (else RECALA_ORG, else recala org use). |
| `--position` | Yes | New position, starting at 1. |

#### Examples

Set the named shell variables to your own values before running.

```
recala topics up-next move "$TOPIC" --position "$POSITION"
```

**Exit codes:** [`0` OK](https://recala.co/developers/reference/#exit-0), [`1` ERROR](https://recala.co/developers/reference/#exit-1), [`2` USAGE](https://recala.co/developers/reference/#exit-2), [`3` NOT_AUTHENTICATED](https://recala.co/developers/reference/#exit-3), [`4` FORBIDDEN](https://recala.co/developers/reference/#exit-4), [`5` NOT_FOUND](https://recala.co/developers/reference/#exit-5), [`6` CONFLICT](https://recala.co/developers/reference/#exit-6), [`7` INVALID](https://recala.co/developers/reference/#exit-7), [`8` RATE_LIMITED](https://recala.co/developers/reference/#exit-8), [`9` UNAVAILABLE](https://recala.co/developers/reference/#exit-9), [`10` CONFIRMATION_REQUIRED](https://recala.co/developers/reference/#exit-10), [`11` PAYMENT_REQUIRED](https://recala.co/developers/reference/#exit-11).

API commands share the CLI’s HTTP error mapping. [Read human and JSON output rules](https://recala.co/developers/reference/#json-output).

### [`recala topics up-next remove`](https://recala.co/developers/cli/topics/#cmd-topics-up-next-remove)

Remove a topic by id or exact title from Up next (the API may refill it).

writes Acts on an organization

```
recala topics up-next remove TOPIC [OPTIONS]
```

Replace uppercase arguments with your own values. Replace [OPTIONS] with the flags you need, or omit it.

| Flag | Required | Description |
| --- | --- | --- |
| `--json` | No | Print one JSON document (errors as JSON on stderr). |
| `--org` | No | Organization name, slug or id (else RECALA_ORG, else recala org use). |

#### Examples

Set the named shell variables to your own values before running.

```
recala topics up-next remove "$TOPIC"
```

**Exit codes:** [`0` OK](https://recala.co/developers/reference/#exit-0), [`1` ERROR](https://recala.co/developers/reference/#exit-1), [`2` USAGE](https://recala.co/developers/reference/#exit-2), [`3` NOT_AUTHENTICATED](https://recala.co/developers/reference/#exit-3), [`4` FORBIDDEN](https://recala.co/developers/reference/#exit-4), [`5` NOT_FOUND](https://recala.co/developers/reference/#exit-5), [`6` CONFLICT](https://recala.co/developers/reference/#exit-6), [`7` INVALID](https://recala.co/developers/reference/#exit-7), [`8` RATE_LIMITED](https://recala.co/developers/reference/#exit-8), [`9` UNAVAILABLE](https://recala.co/developers/reference/#exit-9), [`10` CONFIRMATION_REQUIRED](https://recala.co/developers/reference/#exit-10), [`11` PAYMENT_REQUIRED](https://recala.co/developers/reference/#exit-11).

API commands share the CLI’s HTTP error mapping. [Read human and JSON output rules](https://recala.co/developers/reference/#json-output).

### [`recala topics why`](https://recala.co/developers/cli/topics/#cmd-topics-why)

Why Recala proposed this topic: the evidence behind it.

read Acts on an organization

```
recala topics why TOPIC_ID [OPTIONS]
```

Replace uppercase arguments with your own values. Replace [OPTIONS] with the flags you need, or omit it.

| Flag | Required | Description |
| --- | --- | --- |
| `--json` | No | Print one JSON document (errors as JSON on stderr). |
| `--org` | No | Organization name, slug or id (else RECALA_ORG, else recala org use). |

#### Examples

Read the evidence behind a topic.

```
recala topics why "$TOPIC_ID"
```

**Exit codes:** [`0` OK](https://recala.co/developers/reference/#exit-0), [`1` ERROR](https://recala.co/developers/reference/#exit-1), [`2` USAGE](https://recala.co/developers/reference/#exit-2), [`3` NOT_AUTHENTICATED](https://recala.co/developers/reference/#exit-3), [`4` FORBIDDEN](https://recala.co/developers/reference/#exit-4), [`5` NOT_FOUND](https://recala.co/developers/reference/#exit-5), [`6` CONFLICT](https://recala.co/developers/reference/#exit-6), [`7` INVALID](https://recala.co/developers/reference/#exit-7), [`8` RATE_LIMITED](https://recala.co/developers/reference/#exit-8), [`9` UNAVAILABLE](https://recala.co/developers/reference/#exit-9), [`11` PAYMENT_REQUIRED](https://recala.co/developers/reference/#exit-11).

API commands share the CLI’s HTTP error mapping. [Read human and JSON output rules](https://recala.co/developers/reference/#json-output).