docs
// Tools

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:

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

With a Custom Model Identifier

bash
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):

bash
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:

bash
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:

bash
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:

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

bash
erectl embeddings create \ --endpoint my-embed-endpoint \ --input "smoke test"

Embed and Pipe the Vector to a File

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

Compare Dimension Reduction

bash
# 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

bash
#!/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.