erectl 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 erectl; 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 erectl endpoints get
to see what the endpoint is actually configured with.
Create Embedding
The create subcommand (default) generates an embedding for the input text:
erectl embeddings create \
--endpoint my-embed-endpoint \
--input "The capital of France is Paris."
With a Custom Model Identifier
erectl 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):
erectl 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:
erectl 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:
erectl 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 Erebine Inference Microservice (EIM) serving the model, as a downstream error (the router only enforces dimensions >= 1). |
--workspace <name|ws_id> |
string | key's workspace | Workspace the call is made in: its ws_ id or its name, matched among every workspace your key can list. Its token budget gates the call, its usage lands there, and its retention setting applies. Without it, the key's one workspace or the project's default workspace is used. |
-o, --output <fmt> |
string | table |
Global flag. Set to json for the raw API response. See the erectl CLI hub. |
--quiet |
boolean | false |
Global flag. Suppresses the progress spinner. See the erectl CLI hub. |
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
}
}
data[].object is always "embedding";
usage.prompt_tokens and usage.total_tokens are both
decoded by the erectl 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
erectl embeddings create \
--endpoint my-embed-endpoint \
--input "smoke test"
Embed and Pipe the Vector to a File
erectl embeddings create \
--endpoint my-embed-endpoint \
--input "document text here" \
-o json | jq '.data[0].embedding' > vector.json
Compare Dimension Reduction
# Full dimensions
erectl embeddings create --endpoint my-embed-endpoint --input "hello"
# Reduced dimensions
erectl 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"
erectl 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.