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

# Using the CLI

> Install the Remyx CLI, authenticate, and manage Research Interests, recommendations, and search from your terminal.

The **Remyx CLI** is the command-line companion to Remyx Studio. Manage Research Interests, get personalized recommendations, search across papers, repos, and models, and install [automated discovery PRs](/platform/discover/outrider) on a repo — all from your terminal. Source and latest command definitions live in the [official repo](https://github.com/remyxai/remyxai-cli).

## Requirements

* **Python 3** and `pip`
* A **Remyx API key** ([get one here](https://engine.remyx.ai/account))

## Installation

```bash theme={null}
pip install remyxai
```

Verify the executable is on your `PATH`:

```bash theme={null}
remyxai --help
```

## Authentication

Remyx authenticates API calls with a bearer token. Export it before running commands:

<CodeGroup>
  ```bash macOS / Linux theme={null}
  export REMYXAI_API_KEY=<your-key-here>
  ```

  ```powershell Windows (PowerShell) theme={null}
  $env:REMYXAI_API_KEY = "<your-key-here>"
  ```
</CodeGroup>

The client uses this variable when calling `https://engine.remyx.ai/api/v1.0`. Do not commit keys; use your shell profile, `.env` (with a loader), or your CI secret store.

***

## Command Overview

| Group               | What it does                                                                               |
| ------------------- | ------------------------------------------------------------------------------------------ |
| `remyxai interests` | Manage Research Interests — the context that drives personalized recommendations           |
| `remyxai papers`    | Get daily recommendations, view digests, and trigger refreshes                             |
| `remyxai search`    | Search across papers, repos, models, and datasets                                          |
| `remyxai outrider`  | Install the [automated discovery PRs](/platform/discover/outrider) GitHub Action on a repo |

Run `remyxai <group> --help` for all options in a group.

***

## Research Interests

Research Interests define what you care about. They drive the recommendation engine — each interest has its own context and daily recommendation cadence.

### List Interests

```bash theme={null}
remyxai interests list
```

Shows all your Research Interests with name, context preview, daily count, and active status.

<CodeGroup>
  ```bash Text output (default) theme={null}
  remyxai interests list
  ```

  ```bash JSON output theme={null}
  remyxai interests list --format json
  ```
</CodeGroup>

### Create an Interest

```bash theme={null}
remyxai interests create \
  --name "Retrieval-Augmented Generation" \
  --context "https://huggingface.co/remyxai/SpaceThinker-Qwen2.5VL-3B" \
  --daily-count 3
```

| Flag                | Description                                                                             | Default                 |
| ------------------- | --------------------------------------------------------------------------------------- | ----------------------- |
| `--name, -n`        | Short label for the interest                                                            | *(prompted if omitted)* |
| `--context, -c`     | Natural language description, or URLs to HuggingFace models, GitHub repos, arXiv papers | *(prompted if omitted)* |
| `--daily-count, -d` | Recommendations per day (1-10)                                                          | 2                       |
| `--inactive`        | Create as inactive (excluded from daily digest until toggled)                           | —                       |
| `--format, -f`      | Output format: `text` or `json`                                                         | `text`                  |

<Tip>
  Run `remyxai interests create` with no flags for an interactive prompt that walks you through each field.
</Tip>

### Get Interest Details

```bash theme={null}
remyxai interests get --interest "Retrieval-Augmented Generation"
```

The `--interest` flag accepts either a **name** (case-insensitive) or a **UUID**.

### Update an Interest

```bash theme={null}
remyxai interests update \
  --interest "Retrieval-Augmented Generation" \
  --context "https://github.com/your-org/your-rag-system" \
  --daily-count 5
```

| Flag                | Description                                                           |
| ------------------- | --------------------------------------------------------------------- |
| `--interest, -i`    | Interest name or UUID (required)                                      |
| `--name, -n`        | New name                                                              |
| `--context, -c`     | New context (invalidates recommendation pool and triggers re-ranking) |
| `--daily-count, -d` | New daily count                                                       |
| `--activate`        | Set active                                                            |
| `--deactivate`      | Set inactive                                                          |

<Note>
  Updating the `context` invalidates the pre-ranked recommendation pool. Run `remyxai papers refresh` afterward to get fresh results immediately.
</Note>

### Toggle Active Status

```bash theme={null}
remyxai interests toggle --interest "Retrieval-Augmented Generation"
```

Toggles between active and inactive without deleting the interest or its recommendation history.

### Delete an Interest

```bash theme={null}
remyxai interests delete --interest "Retrieval-Augmented Generation"
```

Prompts for confirmation. Pass `--yes` to skip:

```bash theme={null}
remyxai interests delete --interest "Retrieval-Augmented Generation" --yes
```

***

## Recommendations

Get personalized resource recommendations based on your Research Interests.

### Daily Digest

```bash theme={null}
remyxai papers digest
```

Shows today's top recommendations grouped by Research Interest. Each entry includes the resource title, source type, relevance score, and why it was recommended.

| Flag           | Description                                 | Default |
| -------------- | ------------------------------------------- | ------- |
| `--limit, -n`  | Max items per interest                      | 5       |
| `--period, -p` | `today`, `week`, or `all`                   | `today` |
| `--format, -f` | `text` or `json`                            | `text`  |
| `--full`       | Show full reasoning text without truncation | —       |

<CodeGroup>
  ```bash Today's digest theme={null}
  remyxai papers digest
  ```

  ```bash This week, JSON output theme={null}
  remyxai papers digest --period week --format json
  ```

  ```bash Full reasoning, 3 per interest theme={null}
  remyxai papers digest --full --limit 3
  ```
</CodeGroup>

### List Recommendations

```bash theme={null}
remyxai papers list
```

Flat list of all recommendations (not grouped by interest). Supports more granular filtering.

| Flag                | Description                                                | Default           |
| ------------------- | ---------------------------------------------------------- | ----------------- |
| `--interest, -i`    | Filter by interest name or UUID                            | *(all interests)* |
| `--limit, -n`       | Max results (1-50)                                         | 20                |
| `--period, -p`      | `today`, `week`, or `all`                                  | `all`             |
| `--source-type, -s` | Filter by source type (`arxiv_paper`, `github_repo`, etc.) | *(all types)*     |
| `--format, -f`      | `text` or `json`                                           | `text`            |
| `--full`            | Show full reasoning text                                   | —                 |

```bash theme={null}
# Papers for a specific interest from this week
remyxai papers list --interest "Retrieval-Augmented Generation" --period week

# Only GitHub repos
remyxai papers list --source-type github_repo
```

### Refresh Recommendations

```bash theme={null}
remyxai papers refresh
```

Triggers an async recommendation refresh. By default, refreshes all active interests. Use `--wait` to block until complete.

| Flag                | Description                                | Default                          |
| ------------------- | ------------------------------------------ | -------------------------------- |
| `--interest, -i`    | Refresh a specific interest (name or UUID) | *(all active)*                   |
| `--num-results, -n` | Items per interest                         | *(uses interest's daily\_count)* |
| `--wait, -w`        | Block until all tasks complete             | —                                |
| `--format, -f`      | `text` or `json`                           | `text`                           |

<CodeGroup>
  ```bash Refresh all, wait for results theme={null}
  remyxai papers refresh --wait
  ```

  ```bash Refresh one interest theme={null}
  remyxai papers refresh --interest "Reinforcement Learning" --wait
  ```
</CodeGroup>

### Check Refresh Status

```bash theme={null}
remyxai papers refresh-status <task_id>
```

Poll the status of an async refresh task (from `papers refresh` without `--wait`).

***

## Search

Search across the Remyx resource index — papers, repos, models, and datasets with Docker availability filtering.

### Query

```bash theme={null}
remyxai search query "retrieval augmented generation for code"
```

| Flag                | Description                                           | Default |
| ------------------- | ----------------------------------------------------- | ------- |
| `--max-results, -n` | Maximum results                                       | 10      |
| `--category, -c`    | Filter by category (can be specified multiple times)  | *(all)* |
| `--docker`          | Only show resources with runnable Docker environments | —       |
| `--no-docker`       | Only show resources without Docker                    | —       |

```bash theme={null}
# Search for Docker-ready resources only
remyxai search query "vision language models" --docker --max-results 5

# Filter by category
remyxai search query "reinforcement learning" --category cs.LG --category cs.AI
```

### Get Resource Details

```bash theme={null}
remyxai search info 2308.12345
```

Returns detailed information for a specific resource by arXiv ID, including full abstract, Docker status, Dockerfile contents, and reference summary.

| Flag           | Description      | Default |
| -------------- | ---------------- | ------- |
| `--format, -f` | `text` or `json` | `text`  |

### List Recent Resources

```bash theme={null}
remyxai search list
```

Browse recently added resources with pagination.

| Flag                       | Description                           | Default |
| -------------------------- | ------------------------------------- | ------- |
| `--limit, -n`              | Number of results                     | 20      |
| `--offset, -o`             | Pagination offset                     | 0       |
| `--category, -c`           | Filter by category (multiple allowed) | *(all)* |
| `--docker` / `--no-docker` | Filter by Docker availability         | *(all)* |

### Catalog Statistics

```bash theme={null}
remyxai search stats
```

Shows aggregate stats: total assets, Docker availability counts, category breakdown, and citation classification coverage.

***

## Outrider

Install [automated discovery PRs](/platform/discover/outrider) on a GitHub repo without leaving the terminal. The CLI drives the same "set it up for me" flow as the web app — your local git is never touched.

### Install on a repo

```bash theme={null}
remyxai outrider init --repo owner/name --auto-interest
```

This drives the Remyx engine so the **Remyx GitHub App** (`remyx-ai[bot]`) sets the repo secrets, writes the workflow, opens a bot-authored setup PR, and — in `auto` mode — merges it and fires the first run. No personal `gh` token is needed; only your `REMYXAI_API_KEY`.

| Flag              | Description                                                                                                                       | Default                                              |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| `--repo`          | Target repo as `owner/name` or a GitHub URL                                                                                       | *(detected from the current directory's git remote)* |
| `--interest, -i`  | Research Interest UUID to wire in                                                                                                 | *(prompted / see `--auto-interest`)*                 |
| `--auto-interest` | Auto-create a Research Interest from the repo (mutually exclusive with `--interest`)                                              | —                                                    |
| `--mode`          | `auto` (provision + merge setup PR + first run), `review` (provision + open setup PR to review), `off` (create the interest only) | `auto`                                               |
| `--anthropic-key` | Anthropic API key to connect as the model provider (Claude Code). Falls back to `$ANTHROPIC_API_KEY`                              | *(only used if no provider is connected)*            |
| `--no-wait`       | Don't block polling for App install / provisioning; print next steps and return                                                   | —                                                    |
| `--dry-run`       | Print the plan and exit without making changes                                                                                    | —                                                    |
| `--yes, -y`       | Skip the confirmation prompt                                                                                                      | —                                                    |

<Info>
  Connect the [GitHub](/platform/manage/connectors#github) and [Claude Code](/platform/manage/connectors#claude-code) (Anthropic API key) integrations in [Connectors](/platform/manage/connectors) first; `outrider init` uses those connections. If the GitHub App isn't installed on the repo, the command surfaces the install link, and you can pass `--anthropic-key` to set the Anthropic key the first time.
</Info>

<CodeGroup>
  ```bash Auto-create the interest and set it all up theme={null}
  remyxai outrider init --repo remyxai/RepoRanger --auto-interest
  ```

  ```bash Wire in an existing interest, review the setup PR theme={null}
  remyxai outrider init --repo owner/name --interest <uuid> --mode review
  ```

  ```bash Non-interactive (CI) theme={null}
  REMYXAI_API_KEY=... ANTHROPIC_API_KEY=... \
    remyxai outrider init --repo owner/name --interest <uuid> --yes
  ```
</CodeGroup>

### Install without the GitHub App

For organizations that can't grant a third-party GitHub App yet (e.g. a pending security review), `setup-local` does the same provisioning using **your own authenticated `gh` CLI** instead of the Remyx App — nothing new to security-review. The running Action opens PRs with the repo's built-in `GITHUB_TOKEN`.

```bash theme={null}
remyxai outrider setup-local --repo owner/name --auto-interest
```

| Flag              | Description                                                                                                   | Default                      |
| ----------------- | ------------------------------------------------------------------------------------------------------------- | ---------------------------- |
| `--repo`          | Target repo as `owner/name` or a GitHub URL                                                                   | *(detected from git remote)* |
| `--interest, -i`  | Research Interest UUID to wire in                                                                             | —                            |
| `--auto-interest` | Auto-create a Research Interest from the repo                                                                 | —                            |
| `--mode`          | `auto` (open + merge setup PR + dispatch first run) or `review` (open the setup PR for you to merge)          | `auto`                       |
| `--anthropic-key` | Anthropic key to set as the `ANTHROPIC_API_KEY` repo secret. Falls back to `$ANTHROPIC_API_KEY`, then prompts | —                            |
| `--dry-run`       | Print the plan + rendered workflow and exit                                                                   | —                            |
| `--yes, -y`       | Skip the confirmation prompt                                                                                  | —                            |

<Note>
  `setup-local` needs an authenticated `gh` (run `gh auth login`, or set `$GITHUB_TOKEN` with `repo` + `workflow` scopes) and admin on the target repo. The only runtime Remyx dependency is the `REMYX_API_KEY` the workflow uses.
</Note>

See [Automated discovery PRs](/platform/discover/outrider) for what the action does once installed, its configuration inputs, and how to review the PRs it opens.

***

## Quick Reference

| Intent                           | Command                                                                 |
| -------------------------------- | ----------------------------------------------------------------------- |
| Get today's digest               | `remyxai papers digest`                                                 |
| Get this week's digest           | `remyxai papers digest --period week`                                   |
| Recommendations for one interest | `remyxai papers list --interest "RAG" --period today`                   |
| Refresh all interests            | `remyxai papers refresh --wait`                                         |
| Refresh one interest             | `remyxai papers refresh --interest "RAG" --wait`                        |
| List interests                   | `remyxai interests list`                                                |
| Create an interest               | `remyxai interests create --name "RAG" --context "..." --daily-count 3` |
| Toggle an interest               | `remyxai interests toggle --interest "RAG"`                             |
| Delete an interest               | `remyxai interests delete --interest "RAG" --yes`                       |
| Search for resources             | `remyxai search query "your query" --max-results 10`                    |
| Search Docker-ready only         | `remyxai search query "your query" --docker`                            |
| Get resource details             | `remyxai search info 2308.12345`                                        |
| Browse recent resources          | `remyxai search list --limit 20`                                        |
| Catalog stats                    | `remyxai search stats`                                                  |
| Install automated discovery PRs  | `remyxai outrider init --repo owner/name --auto-interest`               |
| Install without the GitHub App   | `remyxai outrider setup-local --repo owner/name --auto-interest`        |

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="REMYXAI_API_KEY missing or invalid">
    Export the key in the same shell session you use for `remyxai`. Verify with:

    ```bash theme={null}
    echo $REMYXAI_API_KEY
    ```

    If empty, set it:

    ```bash theme={null}
    export REMYXAI_API_KEY=<your-key-here>
    ```
  </Accordion>

  <Accordion title="Command not found: remyxai">
    The binary may not be on your `PATH`. Check where pip installed it:

    ```bash theme={null}
    pip show remyxai | grep Location
    ```

    On Linux, `pip install` without `sudo` puts the binary in `~/.local/bin`. Either add that to your `PATH` or install with `sudo pip install remyxai`.
  </Accordion>

  <Accordion title="Digest shows 'no new recommendations today'">
    Run `remyxai papers refresh --wait` to trigger a fresh ranking. If recommendations show for `--period week` but not `today`, they were generated on a previous day. Refreshing will surface the latest resources.
  </Accordion>
</AccordionGroup>

***

## Next Steps

* Set up [automated discovery PRs](/platform/discover/outrider) on a repo with `remyxai outrider init`
* Browse commands and source in the [Remyx CLI repo](https://github.com/remyxai/remyxai-cli)
* Connect the [MCP server](/resources/mcp-server) for AI-powered experiment management