---

name: cli-and-tools description: "Operate XTuner legacy command routing, old config-zoo discovery, model conversion planning, chat/evaluation/preprocess tools, and HuggingFace-trainer examples while separating them from V1 direct CLIs." disable-model-invocation: true metadata: disco-role: operating license: Apache 2.0

XTuner legacy CLI and tools

Use this sub-skill when a task is about the legacy top-level xtuner MODE ... router, old predefined config names, old utility scripts, model conversion command planning, legacy chat/evaluation/preprocess commands, or the HuggingFace Trainer example scripts.

Do not use this sub-skill for XTuner V1 direct workflows. Route V1 SFT/pretraining/MLLM training to the training sub-skill, V1 RL/GRPO to reinforcement-learning, V1 JSONL/data protocol details to data-preparation, and V1 model/backend sizing to model-backends.

Fast routing rules

• Legacy CLI: command begins with xtuner list-cfg, copy-cfg, log-dataset, check-custom-dataset, train, test, chat, convert, preprocess, mmbench, eval_refcoco, or list-dataset-format.
• V1 direct CLI: command mentions direct SFT/RL scripts, --model-cfg, --chat_template, GRPO, Ray rollout engines, FSDP/TP/EP/HSDP, or V1 config classes. Route away from this sub-skill.
• Config-zoo search/copy: use the bundled helper instead of importing XTuner or reading every config file body.
• Model conversion: keep converters as reference-only plans unless the user supplies local model/checkpoint/adapter paths, resource approval, and a safe execution environment.
• Chat/evaluation/preprocess: require explicit local assets before execution; these tools can trigger model loads, benchmark reads, or network downloads.

Operating procedure

1. Classify the task as legacy or V1 using the routing rules above.

2. For old config names, search with scripts/find_legacy_configs.py and an explicit config root supplied by the user or environment:

   python scripts/find_legacy_configs.py --config-root /path/to/legacy-configs qlora alpaca --limit 20
   python scripts/find_legacy_configs.py --config-root /path/to/legacy-configs --exact internlm_7b_qlora_alpaca_e3 --copy-to ./configs
   

3. For command syntax and tool behavior, consult legacy CLI reference.

4. For convert pth_to_hf, convert merge, or convert split, consult model conversion reference and explain required inputs before proposing execution.

5. Before running legacy tools, verify the executable path. The current package may not install a console entry point named xtuner; if xtuner is missing, either use a source checkout's legacy tool script explicitly or ask for a checkout/package that includes the legacy router.

6. Apply troubleshooting for missing command entry points, path-vs-snapshot errors, adapter/base mismatches, benchmark asset gaps, distributed-router surprises, and unsafe network/credential risks.

Safety and boundaries

• Never assume this generated skill contains XTuner's original config zoo or converter source. It only contains references and a lightweight search/copy helper.
• Do not crawl unrelated directories for configs. Require an explicit --config-root.
• Do not run GPU-heavy conversion, chat, training, or evaluation commands without user approval and concrete local paths.
• Do not pass secrets, HuggingFace tokens, or private storage credentials into legacy tools unless the user explicitly scopes how to handle them.
• If a task asks for legacy xtuner train mechanics, explain the old command surface here; if it asks for V1 training design, route to training.

Difficult cases this sub-skill supports

• Search old config names for tokens such as qlora and alpaca from a supplied config root without importing XTuner or loading hundreds of source files.
• Explain why a legacy adapter merge needs a base LLM or CLIP snapshot path, an adapter path, a save path, and optional --is-clip for visual-encoder adapters.