xeroctl models - Xerotier

Overview#

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

Pattern

                    xeroctl models                                  # List all models
xeroctl models <MODEL_ID>                       # Show model details
xeroctl models <MODEL_ID> --<action>            # Perform an action on a model
xeroctl models versions <MODEL_ID>              # Manage model versions
xeroctl models probe <MODEL_ID>                 # Probe model capabilities
xeroctl models set-capabilities <MODEL_ID> <cap>...   # Set capabilities (admin)
xeroctl 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 xeroctl 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 xeroctl 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 xeroctl CLI overview.

List Models#

// try this first Run xeroctl 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
xeroctl models

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

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

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

# JSON output
xeroctl 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
xeroctl models 8b1f4c2d-9e7a-4f3b-bc11-2d8e6a4c5f01

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

# JSON output
xeroctl 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
xeroctl models 8b1f4c2d-9e7a-4f3b-bc11-2d8e6a4c5f01 \
  --description "Fine-tuned for code generation" \
  --context-length 8192

# Update multiple technical fields
xeroctl 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
xeroctl models 8b1f4c2d-9e7a-4f3b-bc11-2d8e6a4c5f01 \
  --pre-quantized \
  --pre-quantization-method awq \
  --pre-quantization-bits 4

# Update MoE expert configuration
xeroctl 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
xeroctl models 8b1f4c2d-9e7a-4f3b-bc11-2d8e6a4c5f01 --delete

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

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

# Preview without deleting
xeroctl 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
xeroctl models 8b1f4c2d-9e7a-4f3b-bc11-2d8e6a4c5f01 --share

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

# Show catalog info (role, deployment count, public flag, featured flag, shared date)
xeroctl 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
xeroctl models 8b1f4c2d-9e7a-4f3b-bc11-2d8e6a4c5f01 --revalidate

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

# Set a custom wait timeout (default: 600 seconds)
xeroctl 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
xeroctl models versions 8b1f4c2d-9e7a-4f3b-bc11-2d8e6a4c5f01

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

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

# Rollback to a previous version
xeroctl 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

xeroctl 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
xeroctl models set-capabilities 8b1f4c2d-9e7a-4f3b-bc11-2d8e6a4c5f01 chat tool-use

# Preview without writing
xeroctl 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

xeroctl 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 xeroctl 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
xeroctl 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
xeroctl models "$MODEL_ID" --revalidate --wait
                

Version Promotion Workflow

bash

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

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

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

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

Bulk Delete Old Models

bash

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

# Execute
xeroctl 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

                    xeroctl models 8b1f4c2d-9e7a-4f3b-bc11-2d8e6a4c5f01 --share
xeroctl 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

xeroctl CLI

Model Management API

Model Versioning