xeroctl models

Manage models in your Xerotier project -- list, inspect, update metadata, delete, share to the catalog, revalidate, and manage versions from the command line.

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 <id> # Show model details xeroctl models <id> --<action> # Perform an action on a model xeroctl models versions <id> # Manage model versions

Action flags and metadata update options are mutually exclusive. Only one action flag may be given per invocation. Multiple model IDs are supported only with --delete (bulk deletion).

Back to xeroctl CLI overview.

List Models

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 # Extended details (adds Architecture, Quantization, Context, Parameters, Created) xeroctl models --extended # Wide table output (same extended columns as --extended) xeroctl models -o wide # Paginate results xeroctl models --limit 10 --offset 20 # JSON output xeroctl models -o json

Listing Options

Option Description
--limit <n> Maximum number of results (default 100, max 100).
--offset <n> Pagination offset. When more results exist, a hint is printed at the end of the table.
--extended Show extended model details including architecture, quantization, context length, parameter count, and creation time.

Get Model

Provide a single model ID to display its full details.

bash
# Human-readable key-value output xeroctl models mdl_abc123 # Show full description without truncation xeroctl models mdl_abc123 --full # JSON output xeroctl models mdl_abc123 -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 mdl_abc123 \ --description "Fine-tuned for code generation" \ --context-length 8192 # Update multiple technical fields xeroctl models mdl_abc123 \ --architecture "transformer" \ --quantization "awq" \ --parameter-count 7000000000 \ --hidden-size 4096 \ --num-layers 32 \ --vocab-size 32000 # Mark as pre-quantized xeroctl models mdl_abc123 \ --pre-quantized \ --pre-quantization-method awq \ --pre-quantization-bits 4 # Update MoE expert configuration xeroctl models mdl_abc123 \ --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 mdl_abc123 --delete # Skip confirmation xeroctl models mdl_abc123 --delete --force # Bulk delete (multiple IDs -- only supported with --delete) xeroctl models mdl_abc123 mdl_def456 mdl_ghi789 --delete --force # Preview without deleting xeroctl models mdl_abc123 --delete --dry-run

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

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 mdl_abc123 --share # Remove from catalog xeroctl models mdl_abc123 --unshare # Show catalog info (role, deployment count, public flag, featured flag, shared date) xeroctl models mdl_abc123 --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 mdl_abc123 --revalidate # Queue revalidation and poll until a terminal status is reached xeroctl models mdl_abc123 --revalidate --wait # Set a custom wait timeout (default: 600 seconds) xeroctl models mdl_abc123 --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 mdl_abc123 # Create a new version (semver string required) xeroctl models versions mdl_abc123 --create 2.0.0 xeroctl models versions mdl_abc123 --create 2.0.0 --notes "Improved accuracy on code tasks" # Promote a version to latest xeroctl models versions mdl_abc123 --promote 2.0.0 # Rollback to a previous version xeroctl models versions mdl_abc123 --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.

Options Reference

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

Action Flags (mutually exclusive)

Flag Requires ID Description
--delete Yes (one or more) Delete one or more models. Prompts for confirmation unless --force is set.
--share Yes (one) Share the model to the catalog.
--unshare Yes (one) Remove the model from the catalog.
--revalidate Yes (one) Trigger model file revalidation.
--catalog-info 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 Show extended model details in the listing 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. Default 100, max 100.
--offset <n> Pagination offset when listing.

Examples

Update and Revalidate a Model

bash
MODEL_ID="mdl_abc123" # 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="mdl_abc123" # 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 mdl_old1 mdl_old2 mdl_old3 --delete --dry-run # Execute xeroctl models mdl_old1 mdl_old2 mdl_old3 --delete --force

Share to Catalog and Check Info

bash
xeroctl models mdl_abc123 --share xeroctl models mdl_abc123 --catalog-info

xeroctl CLI

Overview of all xeroctl commands, installation, and configuration.

Model Management API

REST API reference for model lifecycle operations.

Model Versioning

Deep dive into model versioning, promotion, and rollback.