erectl rerank - Erebine

// /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 erectl CLI hub. Two page-specific deltas:

--endpoint <slug> is required on both verbs and has no environment-variable fallback.
--dry-run is honored by both verbs: each prints what it would send and exits without opening a connection. score also skips the endpoint-model lookup, so a dry run reports --model only when you passed it.

The model must match the endpoint -- on score. /v1/score checks the model in the request body against the model the endpoint serves and answers a mismatch with HTTP 404 model_not_found. Omit --model and score reads the endpoint's model name from your project's endpoint listing and sends that. Pass --model <name> to skip the lookup, which an API key confined to a single endpoint has to do because such a key cannot read the project-wide listing.

rerank does no such lookup, and needs none: /v1/rerank ignores the value and its model field is optional. The CLI sends --model verbatim when you pass it and sends no model field at all when you do not; both are accepted, and the response reports the endpoint's configured model id either way. Leave --model off. There is no portability argument for supplying it: a rerank body is query plus documents, while /v1/score takes text_1 plus text_2, so the two bodies are not interchangeable whatever model holds.

Request correlation. A successful /v1/rerank or /v1/score response carries an X-Request-ID header holding the id the router routed under; quote it when reporting a bad result. Error responses from either route carry no such header, so a failed call is correlated by endpoint slug, timestamp, and client IP. erectl does not print response headers; read the id with curl -i against the same endpoint.

// 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

                    erectl 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

                    erectl 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

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

JSON output

bash

                    erectl 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

                    erectl 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

                    erectl 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" | erectl rerank \
  --query "search" \
  --endpoint my-rerank-endpoint \
  --stdin
                

Combined sources

bash

                    cat additional.txt | erectl 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	Optional. Model name to send in the request body, passed through verbatim. `rerank` does not resolve it from the endpoint, and omitting it sends a body with no `model` field -- which `/v1/rerank` accepts, because the route ignores the field and reranks with the endpoint's configured model regardless. There is no portability argument for supplying it: a rerank body is `query` plus `documents`, while `/v1/score` takes `text_1` plus `text_2`, so the two bodies are not interchangeable whatever `model` holds.

// output

rerank output

Default table output for a rerank request. The title carries whatever the API returned in model, which on /v1/rerank is the endpoint's model id rather than its name:

Output (table)

                    Rerank Results (model: 791c4e32-1f0b-4e2c-9e1d-2a7b6c5d4e3f)
 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

                    erectl 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" | erectl score \
  --text1 "hello" \
  --endpoint my-rerank-endpoint \
  --stdin
                

Combined inline and stdin

bash

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

JSON output

bash

                    erectl 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 name to send in the request body. Resolved from the endpoint's configuration when omitted. A value that is not the model the endpoint serves is rejected with HTTP 404 `model_not_found`.

// output

score output

Default table output for a score request. The title carries the endpoint's model name, which /v1/score echoes:

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

The scored list is keyed data, matching the /v1/score wire payload. Keys are emitted in sorted order.

JSON

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

The TEXT column is local. It is reconstructed client-side from --text2 / --stdin, not read off the response; -o json drops it. The CLI also drops the envelope fields it does not use -- id, object, and each entry's object -- so -o json is a subset of the raw /v1/score body, not a copy of it. See Score Response for the full payload.

// examples

Examples

RAG pipeline: rerank retrieved chunks

bash

                    erectl 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

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

erectl score \
  --text1 "automobile" \
  --text2 "car" "vehicle" \
  --endpoint my-rerank-endpoint \
  --dry-run
                

Both verbs stop before the network. A dry run prints a summary of what it would send plus the target endpoint, then exits without issuing a request. Two asymmetries: rerank resolves the base URL and API key before it reaches the dry-run check, so it still fails on an unconfigured context, while score does not; and score skips the endpoint-model lookup, so a dry run echoes --model only when you passed it explicitly.

Score synonym similarity

bash

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

Score from a file of candidates

bash

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

Name the model explicitly instead of resolving it

On score, --model skips the endpoint-listing lookup. Give it the name of the model the endpoint serves; it does not select a different one, and any other value is rejected with HTTP 404 model_not_found. An API key confined to a single endpoint cannot read the project-wide listing, so naming the model this way is the only way such a key can call the verb.

rerank has no lookup to skip and ignores the value, so the flag changes nothing there.

bash

                    erectl score \
  --text1 "best practices for API security" \
  --endpoint my-rerank-endpoint \
  --model "bge-reranker-v2-m3" \
  --text2 \
    "Use API keys and rotate them regularly." \
    "Normalize your database schema." \
    "Validate input on both client and server." \
    "Use HTTPS everywhere."
                

erectl 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

Score synonym similarity

Score from a file of candidates

Name the model explicitly instead of resolving it

erectl CLI Hub

Rerank & Score API

erectl 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

Score synonym similarity

Score from a file of candidates

Name the model explicitly instead of resolving it

erectl CLI Hub

Rerank & Score API

erectl embeddings

Inline strings (`--documents`)

Standard input (`--stdin`)