---

name: training-cli description: "Operate RL Baselines3 Zoo training, resume, checkpoint, evaluation-callback, and log-folder command workflows safely." disable-model-invocation: true metadata: disco-role: operating license: MIT

training-cli

Use this sub-skill when the task is to build, run, resume, or debug RL Baselines3 Zoo training commands for an installed rl_zoo3 package. It covers rl_zoo3 train and python -m rl_zoo3.train, algorithm/environment selection, bounded training runs, continuation from a saved zip, replay-buffer continuation, evaluation/checkpoint callbacks, vectorized environment choice, seeds/UUID/progress/device options, and the training output layout.

Start here

1. Prefer the module command unless the caller specifically needs the console entry point:
   • python -m rl_zoo3.train ... avoids importing the rl_zoo3 console router and its plotting modules.
   • rl_zoo3 train ... is valid when the console entry point imports successfully; if it fails on plotting extras, switch to the module command or use the root install guidance at ../../references/install-and-environment.md.
2. For command recipes and training lifecycle details, read references/training-workflows.md.
3. For the complete train flag surface, read references/cli-reference.md.
4. For known failures and recovery actions, read references/troubleshooting.md.
5. To build a command without launching training, run scripts/train_command_builder.py. The helper validates common unsafe combinations and only prints a shell command.

Operating checklist

• Identify --algo, --env, intended run length, backend/device, and whether this is a smoke test, full run, resume run, or off-policy replay-buffer continuation.
• Use a caller-controlled --log-folder; do not rely on a shared logs/ directory unless that is intentional.
• For any potentially long run, pass --n-timesteps, --eval-freq, --save-freq, --seed, and optionally --uuid and --progress.
• Validate that the Gymnasium environment id is registered before training. For custom packages, pass --gym-packages so registration happens before RL Zoo checks the registry.
• For --trained-agent, provide an existing .zip path. For off-policy continuation, place replay_buffer.pkl next to that zip and use --save-replay-buffer if the replay buffer should be saved again.
• Remember that RL Zoo divides positive --eval-freq and --save-freq by the configured number of training envs (n_envs) before creating callbacks.
• Treat --device cuda and service integrations as optional. Use --device cpu for portable CPU smoke tests.

Boundaries and routes

• Deep YAML/Python config grammar, --conf-file, and complex --hyperparams values: route to ../config-hyperparams/SKILL.md.
• Optuna tuning via -optimize / --optimize-hyperparameters: route to ../tuning-optimization/SKILL.md.
• Loading/enjoying models, best/checkpoint/latest selection, video, and artifact inspection after training: route to ../evaluation-and-artifacts/SKILL.md and ../integrations-hub-tracking/SKILL.md as appropriate.
• Wrappers, callbacks, custom Gymnasium registration modules, and custom algorithm/component imports: route to ../custom-components/SKILL.md.
• Plotting or benchmark interpretation: route to ../plotting-benchmarking/SKILL.md.

Minimal safe command pattern

python -m rl_zoo3.train --algo ppo --env CartPole-v1 --n-timesteps 1000 \
  --log-folder ./runs/rl-zoo --eval-freq 500 --save-freq 500 \
  --seed 123 --device cpu --progress

Use the command builder to produce this pattern safely:

python scripts/train_command_builder.py \
  --algo ppo --env CartPole-v1 --n-timesteps 1000 --log-folder ./runs/rl-zoo \
  --eval-freq 500 --save-freq 500 --seed 123 --device cpu --progress