xeroctl embeddings
Generate embedding vectors from text using the OpenAI-compatible embeddings API. See the xeroctl CLI hub for installation and global options.
Overview
The embeddings command wraps the /v1/embeddings
API endpoint. It accepts a single text string and returns the embedding vector
along with token usage statistics.
An endpoint slug (--endpoint) is always required. The
--input flag is always required.
Note: The --model flag is informational.
The actual model used is determined by the endpoint configuration on the server.
Embedding endpoints must be configured with a compatible embedding model.
Create Embedding
The create subcommand (default) generates an embedding for the input text:
xeroctl embeddings create \
--endpoint my-embed-endpoint \
--input "The capital of France is Paris."
With a Custom Model Identifier
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):
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:
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:
xeroctl embeddings create \
--endpoint my-embed-endpoint \
--input "Hello world" \
-o json
All Options
| Option | Type | Description |
|---|---|---|
--endpoint <slug>required |
string | Endpoint slug for the embedding request. |
--input <text>required |
string | Input text to embed. |
--model <name> |
string | Model identifier. Informational only. Defaults to default. The endpoint configuration determines the actual model used. |
--encoding-format <fmt> |
string | Output format: float (default) or base64. |
--dimensions <n> |
integer | Number of output dimensions. The model must support dimension reduction. |
Example Output
Default table output after a successful embedding request:
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
{
"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
}
}
Examples
Verify an Embedding Endpoint Is Working
xeroctl embeddings create \
--endpoint my-embed-endpoint \
--input "smoke test"
Embed and Pipe the Vector to a File
xeroctl embeddings create \
--endpoint my-embed-endpoint \
--input "document text here" \
-o json | jq '.data[0].embedding' > vector.json
Compare Dimension Reduction
# 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
#!/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
