theseus-cli

Manage theseus ML training job lifecycles via YAML configs and cluster dispatch.

Updated Aug 27, 2026
One-click install
npx skills add https://github.com/Jemoka/theseus --skill theseus-cli
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: theseus-cli
Source: https://github.com/Jemoka/theseus/tree/main/.claude/skills/theseus-cli
Command: npx skills add https://github.com/Jemoka/theseus --skill theseus-cli

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill streamlines the end-to-end workflow for running research training jobs with the theseus CLI by helping users generate and edit YAML configs, run experiments locally, dispatch to remote clusters, start remote REPLs, create bootstrap scripts, and manage checkpoints and restores.

Core Features & Use Cases

  • Config generation: Create canonical YAML job configs from registered job schemas and merge previous configs with overrides.
  • Local execution: Run jobs locally with correct output root handling and restore from checkpoints.
  • Dispatch & orchestration: Submit jobs to clusters (SLURM, SSH, TPU, Volcano), start remote Jupyter REPLs, produce bootstrap scripts, and manage hardware requests and dispatch options.
  • Operational guidance: Provides best practices for tokenization, sweeps, naming, and safety (always show and confirm submit commands).
  • Use case: Generate a pretraining config for gpt/train/pretrain, tokenize data locally, and dispatch a multi-GPU pretraining job to an H100 cluster with checkpointing enabled.

Quick Start

Run uv run theseus configure gpt/train/pretrain train.yaml --chip h100 -n 8 to generate a config skeleton, inspect and edit the YAML as needed, then run or submit after confirming the full command.

Frequently Asked Questions about theseus-cli

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I configure and submit ML training jobs to a SLURM cluster?

To configure ML training jobs for a SLURM cluster, generate a YAML job spec from a registered schema, specify hardware requests like chip and n_chips, and submit via the CLI after confirming the full dispatch command.

What is the workflow for running theseus ML training experiments locally?

Running theseus ML training experiments locally involves creating a YAML config skeleton, editing job specifications, and executing the job via the CLI with correct output root handling and optional checkpoint restoration.

Can I dispatch training jobs to TPU or Volcano clusters using YAML configs?

Yes, you can dispatch training jobs to TPU or Volcano clusters by defining request fields like chip, n_chips, and n_shards in your YAML config and submitting through the CLI with a valid dispatch configuration.

Do I need a dispatch config file to run jobs remotely over SSH?

Yes, submitting jobs remotely over SSH requires an optional ~/.theseus.yaml dispatch config file alongside a valid job schema and job name defined in your repository's YAML job specifications.

How do I manage checkpoints and restore failed training experiments?

To manage checkpoints and restore failed training experiments, use the CLI to operate checkpoint files and bootstrap scripts, allowing you to resume local execution or remote cluster jobs from the last saved state.

What's the best way to generate YAML job specs for multi-GPU pretraining?

The best way to generate YAML job specs for multi-GPU pretraining is to run the CLI configure command with a registered job schema, then merge previous configs with hardware overrides like chip type and chip count.