// Tools

xeroctl embeddings

Embed a string from the shell. Single-input by design; for batch corpora, loop with --quiet -o json or hit the REST surface directly. Supports base64 transport and Matryoshka dimension reduction where the model allows it.

Overview

The embeddings command wraps the /v1/embeddings API endpoint. It accepts a single text string and returns one or more embedding vectors along with token usage statistics.

An endpoint slug (--endpoint) is always required. The --input flag is always required.

Single-string input only. The CLI accepts one string per invocation via --input. Array and token-array inputs are not exposed by xeroctl; for batch embeddings, call the REST embeddings endpoint directly or use the script-loop pattern in the Examples section below.

Endpoints must be configured with task_mode = "embed" and a compatible embedding model. Model identifiers in this page (for example bge-large-en-v1.5) are illustrative; run xeroctl endpoints get to see what the endpoint is actually configured with.

Create Embedding

The create subcommand (default) generates an embedding for the input text:

bash

                    xeroctl embeddings create \
  --endpoint my-embed-endpoint \
  --input "The capital of France is Paris."
                

With a Custom Model Identifier

bash

                    xeroctl embeddings create \
  --endpoint my-embed-endpoint \
  --input "Semantic search query" \
  --model "bge-large-en-v1.5"
                

Reduced Dimensions

Use --dimensions to request a lower-dimensional output vector. The model must support dimension reduction (e.g., Matryoshka embedding models):

bash

                    xeroctl embeddings create \
  --endpoint my-embed-endpoint \
  --input "Hello world" \
  --dimensions 256
                

Base64 Encoding

Use --encoding-format base64 to receive the embedding as a base64-encoded little-endian float32 byte array. This reduces response size by approximately 30% compared to the default JSON float array:

bash

                    xeroctl embeddings create \
  --endpoint my-embed-endpoint \
  --input "Hello world" \
  --encoding-format base64
                

JSON Output

Use -o json to receive the full raw API response object:

bash

                    xeroctl embeddings create \
  --endpoint my-embed-endpoint \
  --input "Hello world" \
  -o json
                

All Options

Option	Type	Default	Description
`--endpoint <slug>`required	string	-	Endpoint slug for the embedding request.
`--input <text>`required	string	-	Input text to embed.
`--model <name>`	string	`default`	Informational only. The endpoint configuration determines the actual model.
`--encoding-format <fmt>`	string	`float`	Output format. `float` for a JSON float array, `base64` for a base64-encoded little-endian float32 byte array.
`--dimensions <n>`	integer	model default	Output vector dimensions. The model must support dimension reduction; unsupported reductions are rejected by the worker as a downstream error (the router only enforces `dimensions >= 1`).
`-o`, `--output <fmt>`	string	`table`	Global flag. Set to `json` for the raw API response. See the xeroctl CLI hub.
`--quiet`	boolean	`false`	Global flag. Suppresses the progress spinner. See the xeroctl CLI hub.

Example Output

Default table output after a successful embedding request:

Output

                    Embedding Result:

Model:          bge-large-en-v1.5
Object:         list
Embeddings:     1
Prompt Tokens:  8
Total Tokens:   8
Embedding [0]:  0.012345, -0.009123, 0.034567, ... (1024 dimensions)
                

For inputs with five or fewer dimensions the full vector is printed. For larger vectors the first three values are shown followed by a dimension count summary.

JSON Output Structure

JSON

                    {
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.012345, -0.009123, 0.034567, ...]
    }
  ],
  "model": "bge-large-en-v1.5",
  "usage": {
    "prompt_tokens": 8,
    "total_tokens": 8
  }
}
                

data[].object is always "embedding"; usage.prompt_tokens and usage.total_tokens are both decoded by the xeroctl client and printed in the default key-value output. The model value above (bge-large-en-v1.5) is illustrative; the server echoes whichever model the endpoint is configured with.

Examples

Verify an Embedding Endpoint Is Working

bash

                    xeroctl embeddings create \
  --endpoint my-embed-endpoint \
  --input "smoke test"
                

Embed and Pipe the Vector to a File

bash

                    xeroctl embeddings create \
  --endpoint my-embed-endpoint \
  --input "document text here" \
  -o json | jq '.data[0].embedding' > vector.json
                

Compare Dimension Reduction

bash

                    # Full dimensions
xeroctl embeddings create --endpoint my-embed-endpoint --input "hello"

# Reduced dimensions
xeroctl embeddings create --endpoint my-embed-endpoint \
  --input "hello" \
  --dimensions 128
                

Script: Embed Multiple Texts

bash

                    #!/bin/bash
TEXTS=("first document" "second document" "third document")
for text in "${TEXTS[@]}"; do
  echo "Embedding: $text"
  xeroctl embeddings create \
    --endpoint my-embed-endpoint \
    --input "$text" \
    --quiet -o json | jq '.data[0].embedding | length'
done
                

Troubleshooting

The CLI surfaces raw API errors verbatim. If a request fails, see the error reference on the REST embeddings page. Common causes: endpoint not configured with task_mode = "embed", requested --dimensions exceeds the model's supported range, or the endpoint slug does not exist in the current project.

xeroctl embeddings

Overview

Create Embedding

With a Custom Model Identifier

Reduced Dimensions

Base64 Encoding

JSON Output

All Options

Example Output

JSON Output Structure

Examples

Verify an Embedding Endpoint Is Working

Embed and Pipe the Vector to a File

Compare Dimension Reduction

Script: Embed Multiple Texts

Troubleshooting

xeroctl CLI Hub

Embeddings API

xeroctl rerank & score