xeroctl rerank - Xerotier

// /v1/rerank + /v1/score

Overview

rerank wraps /v1/rerank; score wraps /v1/score. Both require an endpoint configured with task_mode: "score". Chat or embedding endpoints reject these requests.

Global option group (--base-url, --api-key, --context, --verbose, --timeout, -o) is documented on the xeroctl CLI hub. Two page-specific deltas:

--endpoint <slug> is required on both verbs and has no environment-variable fallback.
--dry-run is honored by rerank only; score accepts the flag from the inherited group but still issues a live call.

Model identity is server-side. The --model flag is informational pass-through. The endpoint configuration determines the actual model used.

Request correlation. The /v1/rerank and /v1/score handlers do not emit an X-Request-ID response header. Correlate by endpoint slug, timestamp, and client IP.

// rerank

rerank

Takes a query and a set of documents, scores each document against the query, returns results ranked by relevance (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
                

// inputs

rerank input sources

rerank accepts documents from three sources, combined before the API call. At least one document is required. The combined input is capped at 1000 entries by the API; exceeding the cap returns HTTP 400.

Inline strings (`--documents`)

bash

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

File paths (positional arguments)

Each positional file's full contents become one document:

bash

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

Standard input (`--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

bash

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

// flags

rerank options

Option	Type	Description
`--query <text>`required	string	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. Counts against the 1000-entry combined cap.
`[file...]`	string...	Positional file paths. Each file's contents become one document. Counts against the 1000-entry combined cap.
`--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.

// output

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

                    {
  "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

score

Computes raw pairwise similarity between a reference text (--text1) and one or more candidate texts (--text2). Results are returned in index order; no reordering.

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
                

// flags

score options

Option	Type	Description
`--text1 <text>`required	string	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. Required unless `--stdin` is used. Counts against the 1000-entry combined cap.
`--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.

// output

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

                    {
  "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 }
}
                

The TEXT column is local. It is reconstructed client-side from --text2 / --stdin; the wire payload carries only index and score per result. -o json drops the column.

// examples

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 (rerank only)

bash

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

Reminder. --dry-run is honored by rerank only. Passing it to xeroctl score is accepted by the parser but the command still issues the live API call.

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 & score

Overview

rerank

Inline documents

Limit to top N results

Include document text in results

JSON output

rerank input sources

Inline strings (`--documents`)

File paths (positional arguments)

Standard input (`--stdin`)

Combined sources

rerank options

rerank output

JSON output structure

score

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 (rerank only)

Score synonym similarity

Score from a file of candidates

Rerank inline documents with a custom model

xeroctl CLI Hub

Rerank & Score API

xeroctl embeddings

Overview

rerank

Inline documents

Limit to top N results

Include document text in results

JSON output

rerank input sources

Inline strings (--documents)

File paths (positional arguments)

Standard input (--stdin)

Combined sources

rerank options

rerank output

JSON output structure

score

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 (rerank only)

Score synonym similarity

Score from a file of candidates

Rerank inline documents with a custom model

xeroctl CLI Hub

Rerank & Score API

xeroctl embeddings

Inline strings (`--documents`)

Standard input (`--stdin`)