Managing models

After creating a model registry, you can manage models in it using different methods depending on the registry type.

Hugging Face model registry: Models are stored on the Hugging Face platform. Refer to the Hugging Face official documentation to manage models.
File system model registry: Models are stored locally. Use the Neutree CLI tool to push, list, or delete models as described in this section. You can also download models from Hugging Face and push them to a file system model registry.

Prerequisites

Before managing models in a file system model registry, complete the following:

Download version 1.2.0 of the Neutree CLI tool for your server’s CPU architecture.

Grant executable permission to the CLI tool.
Terminal window
```
chmod +x neutree-cli-<arch>
```
You can view the help information for the tool with the following command:
Terminal window
```
neutree-cli-<arch> model -h
```
Create an API key and save it securely.

Pushing a model

Use the Neutree CLI tool to push a local model to a file system model registry:

neutree-cli-<arch> model push <local_model_dir> \
  -n <model_name> \
  -d [model_description] \
  -v [model_version] \
  -r <model_registry> \
  -w [workspace] \
  --api-key <api_key> \
  --server-url <server_url>

Parameter descriptions:

Parameter	Description
`<local_model_dir>`	The local directory where the model is stored.
`<model_name>`	The name under which the model is stored in the model registry. The name must consist of lowercase letters, digits, `_`, `-`, or `.`, be no longer than 63 characters, and must start and end with a letter or digit. If you use a model catalog when creating an endpoint, ensure the model name set here matches the model name in the model catalog.
`[model_description]`	Optional. A description of the model.
`[model_version]`	Optional. The version of the model. If left blank, the system generates one automatically. Multiple versions of a model with the same name can exist in a model registry.
`<model_registry>`	The name of the target model registry.
`[workspace]`	Optional. The name of the workspace. Defaults to the `default` workspace if left blank.
`<api_key>`	The API key created in the prerequisites.
`<server_url>`	The address of the control plane, for example `http://localhost:3000`.

If the target model registry is a file system model registry that starts with nfs://, and the node where the model is located can directly access the NFS storage, the transfer speed is faster than routing through the Neutree control plane. You can mount the target NFS path on that node and run the following command to import the model directly:

neutree-cli-<arch> model push <local_model_dir> \
  -n <model_name> \
  -v [model_version] \
  -r <model_registry> \
  -w [workspace] \
  --local-nfs-path <local_nfs_path> \
  [--skip-local-nfs-mount-check] \
  --api-key <api_key> \
  --server-url <server_url>

Parameter descriptions:

Parameter	Description
`<local_nfs_path>`	The local mount directory of the NFS source corresponding to the target model registry. The user running the command must have write permission on this directory.
`--skip-local-nfs-mount-check`	Optional. If configured, the NFS mount source check is skipped. You can configure this parameter when the command is run on the NFS server and `<local_nfs_path>` points to the export root directory of the model registry instead of a local mount point. Make sure that `<local_nfs_path>` corresponds to the export root directory of the model registry. Otherwise, endpoints may fail to read the model.

Viewing models

Use the following command to view models in a file system model registry:

neutree-cli-<arch> model list -r <model_registry> \
  -w [workspace] \
  --api-key <api_key> \
  --server-url <server_url> \
  [--search <keyword>] \
  [--limit <number>] \
  [--offset <number>] \
  [-o table|json|yaml]

Parameter descriptions:

Parameter	Description
`<model_registry>`	The name of the target model registry.
`[workspace]`	Optional. The name of the workspace. Defaults to the `default` workspace if left blank.
`<api_key>`	The API key created in the prerequisites.
`<server_url>`	The address of the control plane, for example `http://localhost:3000`.
`--search <keyword>`	Optional. View only models whose names match the keyword.
`--limit <number>`	Optional. Limit the number of returned models. Set this parameter to `0` to use the server-side default value.
`--offset <number>`	Optional. Skip the specified number of models before returning results.
`-o table	json

The default table output contains the following information:

Information	Description
`NAME`	Model name.
`VERSIONS`	Model versions. If multiple versions exist, the first version is displayed with the number of remaining versions.
`ALIAS`	Model alias. If no alias is set, `-` is displayed.
`SIZE`	Model size.
`CREATION_TIME`	Model creation time.

After the command is run, the CLI displays the current returned range and the total number in standard error output. If the model registry cannot return the total number, the total number is displayed as unknown.

Viewing model details

Use the following command to view the details of a specified model version in a file system model registry:

neutree-cli-<arch> model get <model_name>:<model_version> \
  -r <model_registry> \
  -w [workspace] \
  --api-key <api_key> \
  --server-url <server_url> \
  [-o table|json|yaml]

Parameter descriptions:

Parameter	Description
`<model_name>`	The name under which the model is stored in the model registry.
`<model_version>`	The model version.
`<model_registry>`	The name of the target model registry.
`[workspace]`	Optional. The name of the workspace. Defaults to the `default` workspace if left blank.
`<api_key>`	The API key created in the prerequisites.
`<server_url>`	The address of the control plane, for example `http://localhost:3000`.
`-o table	json

The default table output displays the model name, version, alias, size, creation time, labels, and model information. If the model registry does not record an alias, - is displayed. If the model registry has checked a model information field but cannot determine its value, the field is displayed as unknown.

Model information fields may include source markers:

Source	Description
`auto`	The field is read by the model registry from the model checkpoint.
`derived`	The field is derived by the model registry from other checkpoint fields.
`manual`	The field is manually supplemented by the user.

When -o json or -o yaml is used, the CLI outputs the structured model data returned by the server, which is convenient for script parsing or model field verification.

Deleting a model

Prerequisites

Check Viewing models to retrieve the version of the model to delete.
Confirm that no endpoints are currently using the model version to be deleted.
Confirm that no endpoints are using the latest version or have no version specified when using this model.

Procedure

Use the following command to delete a model from a file system model registry:

neutree-cli-<arch> model delete <model_name>:<model_version> \
  -r <model_registry> \
  -w [workspace] \
  --api-key <api_key> \
  --server-url <server_url>

Parameter descriptions:

Parameter	Description
`<model_name>`	The name of the model in the model registry.
`<model_version>`	The version of the model.
`<model_registry>`	The name of the target model registry.
`[workspace]`	Optional. The name of the workspace. Defaults to the `default` workspace if left blank.
`<api_key>`	The API key created in the prerequisites.
`<server_url>`	The address of the control plane, for example `http://localhost:3000`.

Downloading a model from Hugging Face

Skip this section for file system model registries.

Install the Hugging Face CLI tool. Refer to the Hugging Face official documentation.
Log in to Hugging Face:
Terminal window
```
hf auth login
```
Use the hf download command to download a model to a local directory. The following examples cover common scenarios:
- Downloading a complete model
  
  Downloads the complete model from Hugging Face to a local directory, for example, downloading the Qwen/Qwen3-0.6B model to ./test-model:
  Terminal window
```
hf download Qwen/Qwen3-0.6B --local-dir ./test-model
```
- Selectively downloading specific files
  
  For large model repositories, use --include and --exclude to control what is downloaded:
  - Download only a specific precision variant. For example, download only the Q8.0 GGUF model:
    Terminal window
    hf download microsoft/Phi-3-mini-4k-instruct-gguf \ --include "*q8_0.gguf" \ --local-dir ./phi3-q8
  - Download multiple types of key files. For example, download the Q8.0 model along with configuration files:
    Terminal window
    hf download microsoft/Phi-3-mini-4k-instruct-gguf \ --include "*q8_0.gguf" \ --include "*.json" \ --include "*.txt" \ --local-dir ./phi3-q8
  - Exclude unnecessary large files. For example, download Qwen/Qwen3-0.6B but exclude large weight files:
    Terminal window
    hf download Qwen/Qwen3-0.6B \ --exclude "*.safetensors" \ --exclude "pytorch_model.bin" \ --local-dir ./qwen3-lightweight

After downloading the model to a local directory and completing the prerequisites, you can push, view, or delete models as needed.