CLI

The worldjen CLI wraps the Python SDK and REST API for terminal workflows. Use it for automation, runner operations, and quick inspection from CI or an agent.

Install

Install the core package:

pip install worldjen

Install the runner extra on GPU machines that should operate the local runner service:

pip install "worldjen[runner]"

Runner service commands require Linux with systemd.

Configure

Most commands use WORLDJEN_API_KEY or --api-key.

export WORLDJEN_API_KEY="wjk_..."
worldjen --version

Commands that return data support --json for machine-readable output.

Score

Score is the single-clip surface. Upload one video at a time and get raw dimension scores back. Each user has exactly one Score session that the CLI manages.

worldjen score get
worldjen score reset
worldjen score upload clip.mp4 --prompt "a cat sitting on a windowsill" --wait
worldjen score upload clip.mp4 --dimensions aesthetic_quality,dynamic_degree --output json

Pass --wait to poll until scores land or --timeout elapses. Default poll interval is 3s; pass --poll-interval to tune.

Rank

Rank is the comparative surface — upload multiple clips that share a prompt and get a leaderboard. The session locks to the first prompt; omit --prompt on subsequent uploads or pass the same string. Passing a different prompt fails with exit 2 and a helpful message; reset the session to start over.

worldjen rank get
worldjen rank upload variant_a.mp4 --prompt "a cat" --wait
worldjen rank upload variant_b.mp4 --wait    # uses the locked prompt
worldjen rank current
worldjen rank reset

Bench

Bench creates and manages full benchmark runs that execute on a worker queue. Use it when you need many prompts evaluated against one or more models. IDs come from the dashboard or list commands. Reasoning and generated summaries are off by default; add --reasoning to store both.

worldjen bench create \
  --name nightly-comparison \
  --dimensions subject_consistency,motion_smoothness \
  --runner-id RUNNER_ID \
  --model-id MODEL_ID \
  --reasoning

Add optional runner pipeline kwargs with inline JSON or a .json file:

worldjen bench create \
  --name tuned-sampler \
  --dimensions subject_consistency \
  --runner-id RUNNER_ID \
  --model-id MODEL_ID \
  --run-instructions ./pipeline-options.json

Bench commands:

Command	Purpose
worldjen bench create	Create and enqueue a run
worldjen bench list [--status STATUS] [--page N] [--limit N]	List runs
worldjen bench get RUN_ID	Show run metadata
worldjen bench cancel RUN_ID	Cancel a run
worldjen bench delete RUN_ID	Delete a run
worldjen bench logs RUN_ID	Fetch logs
worldjen bench csv RUN_ID [-o results.csv]	Download CSV
worldjen bench videos RUN_ID	List generated media
worldjen bench download-videos RUN_ID [-o ./videos]	Download generated media

There is no worldjen bench run-with-pipeline — Python callables don't survive shell arguments. Use worldjen.bench.run_with_pipeline(...) from Python instead.

Dimensions

worldjen dimensions list
worldjen dimensions list --model-type t2v
worldjen dimensions list --model-type t2i --json

Use this before running scoring or bench commands from scripts so the script can choose dimensions compatible with the model type.

Models

worldjen models list
worldjen models list-base
worldjen models list-ref

worldjen models create \
  --name LTX-2 \
  --provider huggingface \
  --hf-repo-id Lightricks/LTX-2 \
  --type text_to_video

worldjen models delete MODEL_ID

For private Hugging Face repos, pass --hf-token TOKEN or set WORLDJEN_HF_TOKEN.

Runners

Runner commands are split into backend account operations and local machine operations.

Backend operations:

worldjen runner list
worldjen runner create --name gpu-01 --display-name "A100 worker"
worldjen runner delete --runner-id RUNNER_ID

Local operations:

worldjen runner register --token TOKEN --name gpu-01
worldjen runner install --name gpu-01
worldjen runner start --name gpu-01
worldjen runner status --name gpu-01
worldjen runner logs --name gpu-01 -f
worldjen runner stop --name gpu-01
worldjen runner uninstall --name gpu-01

Every runner subcommand accepts --name INSTANCE and defaults to default. Instance names must match [a-zA-Z0-9][a-zA-Z0-9_-]{0,63}. Each instance has its own config file, key file, and worldjen-runner@{name} systemd service, so one host can run multiple runners side by side.

worldjen runner create creates the backend runner, registers this machine, installs the local systemd service, and starts it. worldjen runner delete removes the backend runner, stops and uninstalls the local service, and deletes the local config.

Projects and preferences

worldjen projects list
worldjen projects get PROJECT_ID
worldjen projects create --name "Demo project"

worldjen preferences get
worldjen preferences set-notifications true
worldjen preferences set-cache-i2v-images false

API keys

worldjen api-keys list

Create and revoke keys in the dashboard.

Exit codes

Every command maps typed SDK errors to predictable exit codes:

Code	Meaning
0	Success
1	Not found, rate-limited, or server error
2	Auth missing, validation failure, or rank prompt mismatch
130	Interrupted (Ctrl-C)

SDK vs CLI

Use the CLI for shell automation and runner service control. Use the Python SDK when generation and orchestration live inside Python. Use the REST API when you need language-neutral HTTP.