xeroctl rerank - Xerotier

Overview

Two commands are provided for cross-encoder inference:

rerank -- Scores a set of candidate documents against a query and returns them sorted by relevance score in descending order. Wraps the /v1/rerank endpoint.
score -- Computes raw similarity scores between a reference text and one or more candidate texts. Wraps the /v1/score endpoint.

Both commands require a scoring endpoint -- one configured with task_mode: "score". General chat or embedding endpoints will reject these requests.

Note: The --model flag is informational pass-through on both commands. The endpoint configuration determines the actual model used.

rerank Command

The rerank command accepts a query and a set of documents, scores each document against the query, and returns results ranked by relevance score (highest first).

Inline Documents

Pass documents as quoted strings with --documents:

bash

                    xeroctl rerank \
  --query "What is the capital of France?" \
  --endpoint my-rerank-endpoint \
  --documents \
    "Berlin is the capital of Germany." \
    "Paris is the capital of France." \
    "Tokyo is the capital of Japan." \
    "France is a country in Western Europe."
                

Limit to Top N Results

bash

                    xeroctl rerank \
  --query "machine learning tutorials" \
  --endpoint my-rerank-endpoint \
  --documents "intro to neural nets" "SQL basics" "deep learning guide" \
  --top-n 2
                

Include Document Text in Results

Use --return-documents to include the source document text in each result row:

bash

                    xeroctl rerank \
  --query "climate change solutions" \
  --endpoint my-rerank-endpoint \
  --documents "solar panels reduce emissions" "sports statistics" \
  --return-documents
                

JSON Output

bash

                    xeroctl rerank \
  --query "search term" \
  --endpoint my-rerank-endpoint \
  --documents "doc one" "doc two" \
  -o json
                

Document Input Sources

The rerank command accepts documents from three sources. All sources are combined before the API call is made. At least one document is required.

Inline Strings (`--documents`)

bash

                    xeroctl rerank \
  --query "search" \
  --endpoint my-rerank-endpoint \
  --documents "first document text" "second document text"
                

File Paths (Positional Arguments)

Pass file paths as positional arguments. The full file contents are used as the document text:

bash

                    xeroctl rerank \
  --query "search" \
  --endpoint my-rerank-endpoint \
  doc1.txt doc2.txt doc3.txt
                

Standard Input (`--stdin`)

Pipe a document through stdin. All of stdin is read as a single document:

bash

                    echo "document text from a pipeline" | xeroctl rerank \
  --query "search" \
  --endpoint my-rerank-endpoint \
  --stdin
                

Combined Sources

All three sources can be used together in a single invocation:

bash

                    cat additional.txt | xeroctl rerank \
  --query "search" \
  --endpoint my-rerank-endpoint \
  --documents "inline doc" \
  file1.txt \
  --stdin
                

rerank Options

Option	Type	Description
`--query <text>`required	string	The search query to rank documents against.
`--endpoint <slug>`required	string	Endpoint slug. Must be a scoring endpoint.
`--documents <text>...`	string...	One or more inline document strings. Variadic -- accepts multiple values.
`[file...]`	string...	Positional file paths. Each file's contents become one document.
`--stdin`	flag	Read a single document from standard input.
`--top-n <n>`	integer	Maximum number of results to return. Returns all results when omitted.
`--return-documents`	flag	Include original document text in the result table. Long documents are truncated to 80 characters in the table view.
`--model <name>`	string	Model identifier passed through to the API. Informational only.

rerank Output

Default table output for a rerank request:

Output (table)

                    Rerank Results (model: bge-reranker-v2-m3)
 RANK  INDEX     SCORE
    1      1  0.987654
    2      3  0.741230
    3      0  0.123456
    4      2  0.045678

  Total Tokens:  48
                

With --return-documents:

Output (table with documents)

                    Rerank Results (model: bge-reranker-v2-m3)
 RANK  INDEX     SCORE  DOCUMENT
    1      1  0.987654  Paris is the capital of France.
    2      3  0.741230  France is a country in Western Europe.
    3      0  0.123456  Berlin is the capital of Germany.
    4      2  0.045678  Tokyo is the capital of Japan.
                

JSON Output Structure

JSON

                    {
  "id": "rerank-...",
  "model": "bge-reranker-v2-m3",
  "results": [
    {
      "index": 1,
      "relevance_score": 0.987654,
      "document": { "text": "Paris is the capital of France." }
    },
    {
      "index": 3,
      "relevance_score": 0.741230,
      "document": { "text": "France is a country in Western Europe." }
    }
  ],
  "usage": { "total_tokens": 48 }
}
                

score Command

The score command computes raw pairwise similarity scores between a reference text (--text1) and one or more candidate texts (--text2). Results are not reordered -- they are returned in index order.

Basic Usage

bash

                    xeroctl score \
  --text1 "hello" \
  --text2 "hi" "hey" "greetings" \
  --endpoint my-rerank-endpoint
                

From Standard Input

Read candidate texts from stdin, one per line:

bash

                    echo -e "hi\nhey\ngreetings" | xeroctl score \
  --text1 "hello" \
  --endpoint my-rerank-endpoint \
  --stdin
                

Combined Inline and Stdin

bash

                    echo "additional candidate" | xeroctl score \
  --text1 "reference sentence" \
  --text2 "candidate one" "candidate two" \
  --endpoint my-rerank-endpoint \
  --stdin
                

JSON Output

bash

                    xeroctl score \
  --text1 "hello" \
  --text2 "hi" "hey" \
  --endpoint my-rerank-endpoint \
  -o json
                

score Options

Option	Type	Description
`--text1 <text>`required	string	The reference text to score against.
`--endpoint <slug>`required	string	Endpoint slug. Must be a scoring endpoint.
`--text2 <text>...`	string...	One or more candidate texts. Variadic -- accepts multiple values. Required unless `--stdin` is used.
`--stdin`	flag	Read candidate texts from stdin, one per line. Blank lines are ignored.
`--model <name>`	string	Model identifier passed through to the API. Informational only.

score Output

Default table output for a score request:

Output (table)

                    Score Results (model: bge-reranker-v2-m3)
 INDEX     SCORE  TEXT
     0  0.912345  hi
     1  0.874321  hey
     2  0.841209  greetings

  Total Tokens:  12
                

JSON Output Structure

JSON

                    {
  "id": "score-...",
  "model": "bge-reranker-v2-m3",
  "results": [
    { "index": 0, "score": 0.912345 },
    { "index": 1, "score": 0.874321 },
    { "index": 2, "score": 0.841209 }
  ],
  "usage": { "total_tokens": 12 }
}
                

Examples

RAG Pipeline: Rerank Retrieved Chunks

bash

                    xeroctl rerank \
  --query "how to configure TLS in nginx" \
  --endpoint my-rerank-endpoint \
  --top-n 3 \
  --return-documents \
  chunks/chunk-001.txt \
  chunks/chunk-002.txt \
  chunks/chunk-003.txt \
  chunks/chunk-004.txt \
  chunks/chunk-005.txt
                

Dry Run to Inspect Inputs

bash

                    xeroctl rerank \
  --query "test query" \
  --endpoint my-rerank-endpoint \
  --documents "doc a" "doc b" \
  --top-n 1 \
  --dry-run
                

Score Synonym Similarity

bash

                    xeroctl score \
  --text1 "automobile" \
  --text2 "car" "vehicle" "bicycle" "train" \
  --endpoint my-rerank-endpoint
                

Score From a File of Candidates

bash

                    cat candidates.txt | xeroctl score \
  --text1 "reference document text" \
  --endpoint my-rerank-endpoint \
  --stdin \
  -o json | jq '.results | sort_by(-.score)[:5]'
                

Rerank Inline Documents With a Custom Model

bash

                    xeroctl rerank \
  --query "best practices for API security" \
  --endpoint my-rerank-endpoint \
  --model "bge-reranker-v2-m3" \
  --documents \
    "Use API keys and rotate them regularly." \
    "Normalize your database schema." \
    "Validate input on both client and server." \
    "Use HTTPS everywhere." \
  --top-n 3 \
  --return-documents
                

`xeroctl rerank` & `xeroctl score`

Overview

rerank Command

Inline Documents

Limit to Top N Results

Include Document Text in Results

JSON Output

Document Input Sources

Inline Strings (`--documents`)

File Paths (Positional Arguments)

Standard Input (`--stdin`)

Combined Sources

rerank Options

rerank Output

JSON Output Structure

score Command

Basic Usage

From Standard Input

Combined Inline and Stdin

JSON Output

score Options

score Output

JSON Output Structure

Examples

RAG Pipeline: Rerank Retrieved Chunks

Dry Run to Inspect Inputs

Score Synonym Similarity

Score From a File of Candidates

Rerank Inline Documents With a Custom Model

xeroctl CLI Hub

Reranking & Scoring API

xeroctl embeddings

xeroctl rerank & xeroctl score

Overview

rerank Command

Inline Documents

Limit to Top N Results

Include Document Text in Results

JSON Output

Document Input Sources

Inline Strings (--documents)

File Paths (Positional Arguments)

Standard Input (--stdin)

Combined Sources

rerank Options

rerank Output

JSON Output Structure

score Command

Basic Usage

From Standard Input

Combined Inline and Stdin

JSON Output

score Options

score Output

JSON Output Structure

Examples

RAG Pipeline: Rerank Retrieved Chunks

Dry Run to Inspect Inputs

Score Synonym Similarity

Score From a File of Candidates

Rerank Inline Documents With a Custom Model

xeroctl CLI Hub

Reranking & Scoring API

xeroctl embeddings

`xeroctl rerank` & `xeroctl score`

Inline Strings (`--documents`)

Standard Input (`--stdin`)