erectl models - Erebine

Overview#

The erectl models command group provides full lifecycle management for models stored in your project. It follows the unified command pattern used across all erectl resource commands:

Pattern

                    erectl models                                  # List all models
erectl models <MODEL_ID>                       # Show model details
erectl models <MODEL_ID> --<action>            # Perform an action on a model
erectl models versions <MODEL_ID>              # Manage model versions
erectl models probe <MODEL_ID>                 # Probe model capabilities
erectl models set-capabilities <MODEL_ID> <cap>...   # Set capabilities (admin)
erectl models recommend-for-workspace <WS_ID>  # Recommend models for a workspace
                

Action flags and metadata update options are mutually exclusive: only one action flag per invocation, and multiple IDs only with --delete (bulk).

// how to read this page

Placeholders: Angle-bracketed tokens are substitutions. <MODEL_ID> is the bare UUID the router returns from erectl models (for example 8b1f4c2d-9e7a-4f3b-bc11-2d8e6a4c5f01). <WS_ID> is the external workspace id (ws_ prefix). Paste your own value; the literal sample UUIDs in examples will 404.
Context: Every call uses the active deployment: base URL and API key (the project id is derived from base_url). Switch with erectl config use <name> or override per-call with --context.
Catalog: No preloaded model catalog ships. Every model in your project was uploaded or registered by a workspace member. Description strings in examples are illustrative free-form text.
Auth scope: All mutations (PATCH, DELETE, share / unshare, revalidate, version ops) are served by the inference route group and share the inference sliding-window rate limiter. Any API key valid for inference on this project drives them.

Back to erectl CLI overview.

List Models#

// try this first Run erectl models with no arguments to print the table of IDs you can substitute into every other example on this page. Append --help to any subcommand for the in-CLI reference.

Omit all IDs to list models in your project. The default table output includes ID, Name, Format, Size, Status, Version, and Shared columns.

bash

                    # Basic listing
erectl models

# Wide table output (adds Architecture, Quantization, Context, Parameters, Created)
erectl models -o wide

# Request extended fields on the JSON response (no effect on text tables)
erectl models --extended -o json

# Paginate results
erectl models --limit 10 --offset 20

# JSON output
erectl models -o json
                

Listing Options

Option	Description
`--limit <n>`	Maximum number of results. The router applies a server-side ceiling of 100 (and uses 100 as the fallback when no value is supplied); larger values are accepted by the CLI but silently truncated to 100 by the API.
`--offset <n>`	Pagination offset. When more results exist, a hint is printed at the end of the table.
`--extended`	Request extended fields (architecture, quantization, context length, parameter count, creation time) from the API. Only changes the response payload when combined with `-o json`; the default text table is unaffected. To see the extra columns in a table, use `-o wide`.

Get Model#

Provide a single model ID to display its full details.

bash

                    # Human-readable key-value output
erectl models 8b1f4c2d-9e7a-4f3b-bc11-2d8e6a4c5f01

# Show full description without truncation
erectl models 8b1f4c2d-9e7a-4f3b-bc11-2d8e6a4c5f01 --full

# JSON output
erectl models 8b1f4c2d-9e7a-4f3b-bc11-2d8e6a4c5f01 -o json
                

The detail view includes ID, Name, Created, Owner, Format, Size, Status, Version, Is Latest, Description, Architecture, Quantization, Context Length, Parameters, Workload Type, and Shared.

The description is truncated to 120 characters by default. Use --full to display it in its entirety.

Update Metadata#

Provide one or more update options alongside a model ID to patch the model's metadata. Any combination of options may be specified in a single call. Action flags and update options cannot be combined.

bash

                    # Update description and context length
erectl models 8b1f4c2d-9e7a-4f3b-bc11-2d8e6a4c5f01 \
  --description "Fine-tuned for code generation" \
  --context-length 8192

# Update multiple technical fields
erectl models 8b1f4c2d-9e7a-4f3b-bc11-2d8e6a4c5f01 \
  --architecture "transformer" \
  --quantization "awq" \
  --parameter-count 7000000000 \
  --hidden-size 4096 \
  --num-layers 32 \
  --vocab-size 32000

# Mark as pre-quantized
erectl models 8b1f4c2d-9e7a-4f3b-bc11-2d8e6a4c5f01 \
  --pre-quantized \
  --pre-quantization-method awq \
  --pre-quantization-bits 4

# Update MoE expert configuration
erectl models 8b1f4c2d-9e7a-4f3b-bc11-2d8e6a4c5f01 \
  --num-experts 64 \
  --num-experts-per-tok 2
                

Metadata Options

Option	Type	Description
`--description <text>`	string	Human-readable description of the model.
`--license <text>`	string	License identifier or URL (e.g., "MIT", "apache-2.0").
`--architecture <text>`	string	Model architecture (e.g., "transformer", "mamba").
`--quantization <method>`	string	Runtime quantization method applied by the serving backend.
`--context-length <n>`	integer	Maximum context length in tokens.
`--parameter-count <n>`	integer	Total number of model parameters.
`--hidden-size <n>`	integer	Hidden layer dimensionality.
`--num-layers <n>`	integer	Number of transformer layers.
`--vocab-size <n>`	integer	Vocabulary size.
`--workload-type <type>`	string	Intended workload (e.g., "inference", "embedding", "reranking").
`--torch-dtype <dtype>`	string	Native PyTorch dtype: `float16`, `bfloat16`, or `float32`.
`--num-experts <n>`	integer	Total number of MoE experts.
`--num-experts-per-tok <n>`	integer	Number of experts activated per token (MoE models).
`--pre-quantized`	flag	Mark the model as pre-quantized (weights stored in quantized form).
`--pre-quantization-method <m>`	string	Pre-quantization algorithm: `gptq`, `awq`, or `compressed-tensors`.
`--pre-quantization-bits <n>`	integer	Bit width of the pre-quantization: `4` or `8`.

Delete a Model#

Delete a single model or multiple models in bulk. A confirmation prompt is shown unless --force is supplied. Use --dry-run to preview the operation without making changes.

bash

                    # Delete with confirmation prompt
erectl models 8b1f4c2d-9e7a-4f3b-bc11-2d8e6a4c5f01 --delete

# Skip confirmation
erectl models 8b1f4c2d-9e7a-4f3b-bc11-2d8e6a4c5f01 --delete --force

# Bulk delete (multiple IDs, only supported with --delete)
erectl models 8b1f4c2d-9e7a-4f3b-bc11-2d8e6a4c5f01 2a3c5b6e-7d8f-4019-9c2a-1b4d3e5f6a7c 3f7e8d9a-1c2b-4d5e-8f60-7a8b9c0d1e2f --delete --force

# Preview without deleting
erectl models 8b1f4c2d-9e7a-4f3b-bc11-2d8e6a4c5f01 --delete --dry-run
                

Bulk deletion prints a per-model result ([OK] / [FAIL]) and a summary line showing how many succeeded.

// see also REST: DELETE /v1/models/{id}

Share / Unshare#

Share a model to the project catalog so it can be discovered and deployed by other users. Use --unshare to remove it from the catalog. Use --catalog-info to inspect the current catalog state.

bash

                    # Share to catalog
erectl models 8b1f4c2d-9e7a-4f3b-bc11-2d8e6a4c5f01 --share

# Remove from catalog
erectl models 8b1f4c2d-9e7a-4f3b-bc11-2d8e6a4c5f01 --unshare

# Show catalog info (role, deployment count, public flag, featured flag, shared date)
erectl models 8b1f4c2d-9e7a-4f3b-bc11-2d8e6a4c5f01 --catalog-info
                

Catalog info displays: ID, Catalog Role, Deployment Count, On Shared Agents, Public, Featured, and Shared At.

Revalidate#

Trigger a re-check of the model's files and update its validation status. This is useful after a file has been corrected or a partial upload completed.

bash

                    # Queue revalidation and return immediately
erectl models 8b1f4c2d-9e7a-4f3b-bc11-2d8e6a4c5f01 --revalidate

# Queue revalidation and poll until a terminal status is reached
erectl models 8b1f4c2d-9e7a-4f3b-bc11-2d8e6a4c5f01 --revalidate --wait

# Set a custom wait timeout (default: 600 seconds)
erectl models 8b1f4c2d-9e7a-4f3b-bc11-2d8e6a4c5f01 --revalidate --wait --wait-timeout 300
                

Revalidation Options

Option	Description
`--revalidate`	Trigger model revalidation. Requires a single model ID.
`--wait`	Poll until revalidation reaches a terminal state (active, ready, validated, error, failed, or invalid). Only valid with `--revalidate`.
`--wait-timeout <seconds>`	Maximum seconds to wait when `--wait` is used. Default: 600.

Version Management#

The models versions subcommand manages semantic versions for a model. Versions track deployment history and allow rollback to a previous state.

bash

                    # List all versions for a model
erectl models versions 8b1f4c2d-9e7a-4f3b-bc11-2d8e6a4c5f01

# Create a new version (semver string required)
erectl models versions 8b1f4c2d-9e7a-4f3b-bc11-2d8e6a4c5f01 --create 2.0.0
erectl models versions 8b1f4c2d-9e7a-4f3b-bc11-2d8e6a4c5f01 --create 2.0.0 --notes "Improved accuracy on code tasks"

# Promote a version to latest
erectl models versions 8b1f4c2d-9e7a-4f3b-bc11-2d8e6a4c5f01 --promote 2.0.0

# Rollback to a previous version
erectl models versions 8b1f4c2d-9e7a-4f3b-bc11-2d8e6a4c5f01 --rollback 1.0.0
                

Version Options

Option	Description
`--create <version>`	Create a new version using a semver string (e.g., `2.0.0`).
`--promote <version>`	Mark the given version as the latest active version.
`--rollback <version>`	Roll back to a previously created version.
`--notes <text>`	Version release notes. Only valid with `--create`.

Only one action (--create, --promote, or --rollback) may be specified per invocation.

The version list table shows: Version, ID, Latest, Status, Notes, and Created.

// see also Model Versioning for promotion semantics and rollback safety.

Probe#

Probe a deployed model for its declared capabilities. The router calls the underlying serving backend and returns the capability map as JSON.

bash

erectl models probe 8b1f4c2d-9e7a-4f3b-bc11-2d8e6a4c5f01

If the router deployment has not enabled the probe route, the command exits cleanly with the message "Model probing is not available on this router deployment (501)." Probing is only meaningful for a model that is currently deployed.

Set Capabilities (admin-only)#

Overwrite the capability list for a model. This operation is gated to workspace administrators by the router; non-admin callers receive an authorization error.

bash

                    # Set one or more capabilities
erectl models set-capabilities 8b1f4c2d-9e7a-4f3b-bc11-2d8e6a4c5f01 chat tool-use

# Preview without writing
erectl models set-capabilities 8b1f4c2d-9e7a-4f3b-bc11-2d8e6a4c5f01 chat --dry-run
                

At least one capability name is required. The request fully replaces the existing capability list, it is not additive.

// see also REST: PATCH /v1/models/{id}/capabilities (admin scope)

Recommend For Workspace#

Ask the router for a ranked list of models suited to a given workspace, based on workspace settings and recent usage patterns.

bash

erectl models recommend-for-workspace ws_0123456789abcdef

The default text output shows columns: Model ID, Name, Score, Reason. Use -o json to receive the raw recommendation payload.

Options Reference#

Full reference for all flags and options accepted by erectl models.

Action Flags (mutually exclusive)

Flag	State	Requires ID	Description
`--delete`	destructive	Yes (one or more)	Delete one or more models. Prompts for confirmation unless `--force` is set.
`--share`	reversible	Yes (one)	Share the model to the catalog.
`--unshare`	reversible	Yes (one)	Remove the model from the catalog.
`--revalidate`	safe	Yes (one)	Trigger model file revalidation.
`--catalog-info`	read-only	Yes (one)	Display catalog information for the model.

Modifier Flags

Flag	Description
`--force`	Skip the confirmation prompt on destructive operations.
`--full`	Show the full description instead of truncating to 120 characters.
`--extended`	Request extended fields on the API response. Affects JSON output only; use `-o wide` to render extra columns in the text table.
`--wait`	Poll until revalidation completes. Only valid with `--revalidate`.
`--wait-timeout <n>`	Timeout in seconds for `--wait`. Default: 600.
`--limit <n>`	Maximum number of results when listing. The router enforces a server-side ceiling of 100 and uses 100 as the fallback when omitted.
`--offset <n>`	Pagination offset when listing.

Examples#

Update and Revalidate a Model

bash

                    MODEL_ID="8b1f4c2d-9e7a-4f3b-bc11-2d8e6a4c5f01"

# Set metadata
erectl models "$MODEL_ID" \
  --description "Qwen3 7B instruct, fine-tuned for code" \
  --architecture "transformer" \
  --context-length 32768 \
  --parameter-count 7000000000 \
  --workload-type "inference"

# Revalidate and wait for result
erectl models "$MODEL_ID" --revalidate --wait
                

Version Promotion Workflow

bash

                    MODEL_ID="8b1f4c2d-9e7a-4f3b-bc11-2d8e6a4c5f01"

# Create new version after fine-tuning
erectl models versions "$MODEL_ID" \
  --create 2.1.0 \
  --notes "Reduced hallucination rate on factual queries"

# Verify the version list
erectl models versions "$MODEL_ID"

# Promote once tested
erectl models versions "$MODEL_ID" --promote 2.1.0
                

Bulk Delete Old Models

bash

                    # Preview first
erectl models 4a5b6c7d-8e9f-4012-9a3b-5c6d7e8f9012 5b6c7d8e-9f01-4234-8a4b-6c7d8e9f0123 6c7d8e9f-0123-4456-8b5c-7d8e9f012345 --delete --dry-run

# Execute
erectl models 4a5b6c7d-8e9f-4012-9a3b-5c6d7e8f9012 5b6c7d8e-9f01-4234-8a4b-6c7d8e9f0123 6c7d8e9f-0123-4456-8b5c-7d8e9f012345 --delete --force
                

Share to Catalog and Check Info

bash

                    erectl models 8b1f4c2d-9e7a-4f3b-bc11-2d8e6a4c5f01 --share
erectl models 8b1f4c2d-9e7a-4f3b-bc11-2d8e6a4c5f01 --catalog-info
                

Overview#

List Models#

Listing Options

Get Model#

Update Metadata#

Metadata Options

Delete a Model#

Share / Unshare#

Revalidate#

Revalidation Options

Version Management#

Version Options

Probe#

Set Capabilities (admin-only)#

Recommend For Workspace#

Options Reference#

Action Flags (mutually exclusive)

Modifier Flags

Examples#

Update and Revalidate a Model

Version Promotion Workflow

Bulk Delete Old Models

Share to Catalog and Check Info

erectl CLI

Model Management API

Model Versioning