cli

cli

a basic cli called theseus implemented in click with nice rich driven printouts, etc. not intended to be used for i.e. logging; and instead meant for user-facing interactions

resolve_dispatch_config_path(dispatch_config: str | None) -> str

Resolve the dispatch config path with the standard defaulting policy.

CLI flag wins; otherwise falls back to ~/.theseus.yaml; otherwise errors out. Exits the process on misconfiguration so callers can treat the return as guaranteed-existing.

PUBLIC API. See the contract banner above this function.

setup_logging(verbose: bool) -> None

Configure loguru with appropriate log level.

theseus(verbose: bool) -> None

Theseus CLI for managing and running jobs.

jobs(preload_modules: tuple[str, ...]) -> None

List all available jobs in the registry.

configure(job: str, out_yaml: str, previous: str | None, chip: str | None, n_chips: int | None, n_shards: int | None, preload_modules: tuple[str, ...], overrides: tuple[str, ...]) -> None

Generate a configuration YAML for a job.

JOB: Name of the job to generate config for OUT_YAML: Output path for the generated YAML config OVERRIDES: Optional config overrides in key=value format

run(name: str, yaml_path: str, out_path: str, job: str | None, project: str | None, group: str | None, n_shards: int | None, extra_stages: tuple[str, ...], restore_path: str | None, preload_modules: tuple[str, ...], overrides: tuple[str, ...]) -> None

Run a job with a configuration file.

NAME: Name of the job run YAML_PATH: Path to the configuration YAML file OUT_PATH: Output path for job results OVERRIDES: Optional config overrides in key=value format

submit(name: str, yaml_path: str, dispatch_config: str | None, job: str | None, project: str | None, group: str | None, chip: str | None, n_chips: int | None, n_shards: int | None, mem: str | None, cpu: str | None, cluster: str | None, exclude_cluster: str | None, dirty: bool, uv_targets: tuple[str, ...], extra_stages: tuple[str, ...], tpu_version: str | None, tpu_spot: bool | None, tpu_preemptible: bool | None, volcano_image: str | None, volcano_namespace: str | None, volcano_labels: tuple[str, ...], restore_path: str | None, preload_modules: tuple[str, ...], env_overrides: tuple[str, ...], overrides: tuple[str, ...]) -> None

Submit a job to remote infrastructure via dispatch.

NAME: Name of the job run YAML_PATH: Path to the configuration YAML file OVERRIDES: Optional config overrides in key=value format

repl(dispatch_config: str | None, chip: str | None, n_chips: int | None, n_shards: int | None, mem: str | None, cpu: str | None, cluster: str | None, exclude_cluster: str | None, dirty: bool, sync_mode: bool, update_mode: bool, port: int, startup_timeout: float, slurm_wait_timeout: float | None, uv_targets: tuple[str, ...], tpu_version: str | None, tpu_spot: bool | None, tpu_preemptible: bool | None, volcano_labels: tuple[str, ...]) -> None

Start a remote Jupyter REPL on selected dispatch infrastructure.

bootstrap(name: str, yaml_path: str, out_script: str, job: str | None, project: str | None, group: str | None, chip: str | None, n_chips: int | None, n_shards: int | None, root: str | None, work: str | None, log: str | None, mount: str | None, cache_size: str | None, cache_dir: str | None, all_squash: str | None, dirty: bool, preload_modules: tuple[str, ...], overrides: tuple[str, ...], uv_targets: tuple[str, ...]) -> None

Generate a standalone bootstrap script (like SLURM submit payload).

NAME: Name of the job run YAML_PATH: Path to the configuration YAML file OUT_SCRIPT: Output path for the generated bootstrap shell script OVERRIDES: Optional config overrides in key=value format

checkpoints(name: str, out_path: str, project: str | None, group: str | None) -> None

List available checkpoints for a job.

NAME: Name of the job OUT_PATH: Output path where checkpoints are stored

restore(name: str, checkpoint: str, out_path: str, project: str | None, group: str | None) -> None

Restore and run a job from a checkpoint.

NAME: Name of the job CHECKPOINT: Checkpoint to restore from OUT_PATH: Output path where checkpoints are stored