CLI Reference¶

hylo is one command whose subcommands come from the installed Hylo packages (the hylo.commands entry-point group): what is listed here depends on which repositories are installed. Every page below is the command's own --help.

Command	What it does
`hylo artifact`	verify a sealed artifact and print its manifest
`hylo bench`	benchmark protocols, scorecards and leaderboards
`hylo calibrate`	calibrate a success judge against simulator outcomes
`hylo conformance`	check a config's environment (and agent) against the contracts
`hylo contamination`	check external runs against gate / held-out init states
`hylo evolve`	improvement campaigns: run, status, approve, rollback, shadow
`hylo ingest`	ingest an external data source as a run
`hylo label`	label an ingested run with a calibrated success judge
`hylo learn`	run a learner job (TrainJob JSON) and seal its artifact
`hylo playground`	run the playground: run explorer, live sandbox, campaigns and the workcell control plane
`hylo plugin`	scaffold a plugin package (new) or check one (check)
`hylo plugins`	list plugins
`hylo profile`	show or edit this machine's execution profile (runtimes)
`hylo run`	run an experiment config
`hylo schema`	print a contract JSON Schema
`hylo serve`	serve a policy, a workcell, or one env / agent component
`hylo skills`	archive -> skill library
`hylo store`	the run and artifact store: ids, references, deletion protection, sync between machines
`hylo trace`	summarise a run or an episode trace

hylo artifact¶

usage: hylo artifact [-h] path

positional arguments:
  path

options:
  -h, --help  show this help message and exit

hylo bench¶

usage: hylo bench [-h] {list,show,run,leaderboard,compare} ...

hylo bench: benchmark protocols, scorecards and leaderboards.

positional arguments:
  {list,show,run,leaderboard,compare}
    list                protocols that ship with hylo-bench
    show                a protocol's definition and digest
    run                 run a policy under a protocol and write its scorecard
    leaderboard         rank scorecards per protocol
    compare             paired comparison of two scorecards of one protocol

options:
  -h, --help            show this help message and exit

hylo bench list¶

usage: hylo bench list [-h]

options:
  -h, --help  show this help message and exit

hylo bench show¶

usage: hylo bench show [-h] protocol

positional arguments:
  protocol

options:
  -h, --help  show this help message and exit

hylo bench run¶

usage: hylo bench run [-h] --policy POLICY --name NAME [--out OUT]
                      [--workers WORKERS] [--set KEY=VALUE] [--notes NOTES]
                      protocol

positional arguments:
  protocol           protocol name or YAML path

options:
  -h, --help         show this help message and exit
  --policy POLICY    agent spec JSON, experiment config YAML, or plugin name
  --name NAME        the policy's name on the leaderboard
  --out OUT          runs go to OUT/runs, scorecards to OUT/scorecards
  --workers WORKERS
  --set KEY=VALUE    execution only: env.remote.* (e.g.
                     env.remote.runtime=NAME)
  --notes NOTES

hylo bench leaderboard¶

usage: hylo bench leaderboard [-h] [--json] [dirs ...]

positional arguments:
  dirs

options:
  -h, --help  show this help message and exit
  --json

hylo bench compare¶

usage: hylo bench compare [-h] candidate baseline

positional arguments:
  candidate
  baseline

options:
  -h, --help  show this help message and exit

hylo calibrate¶

usage: hylo calibrate [-h] --judge JUDGE --runs RUNS [RUNS ...]
                      [--splits SPLITS [SPLITS ...]] [--limit LIMIT]
                      [--seed SEED] [--task-prefix TASK_PREFIX]
                      [--target-precision TARGET_PRECISION]
                      [--artifact ARTIFACT] [--out OUT]

options:
  -h, --help            show this help message and exit
  --judge JUDGE         instrument spec as JSON: {"type": ..., "params":
                        {...}}
  --runs RUNS [RUNS ...]
  --splits SPLITS [SPLITS ...]
  --limit LIMIT
  --seed SEED
  --task-prefix TASK_PREFIX
  --target-precision TARGET_PRECISION
  --artifact ARTIFACT   the judge's artifact (directory or store id): excludes
                        its training runs, stores the report
  --out OUT             write report + per-episode records here (JSON)

hylo conformance¶

usage: hylo conformance [-h] [--split SPLIT] [--agent] [--nondeterministic]
                        [--spec-budget SPEC_BUDGET] [--set KEY=VALUE]
                        config

positional arguments:
  config

options:
  -h, --help            show this help message and exit
  --split SPLIT
  --agent               also check the agent (runs two full episodes)
  --nondeterministic    skip the same-seed-same-episode check
  --spec-budget SPEC_BUDGET
                        seconds spec() may take (remote envs start a process)
  --set KEY=VALUE

hylo contamination¶

usage: hylo contamination [-h] [--protected PROTECTED [PROTECTED ...]]
                          [--tolerance TOLERANCE]
                          external [external ...]

positional arguments:
  external

options:
  -h, --help            show this help message and exit
  --protected PROTECTED [PROTECTED ...]
  --tolerance TOLERANCE

hylo evolve¶

usage: hylo evolve [-h] [--set KEY=VALUE] [--reason REASON]
                   [--candidate CANDIDATE] [--split SPLIT] [--publish]
                   {run,status,approve,rollback,shadow} target

positional arguments:
  {run,status,approve,rollback,shadow}
  target                evolve config YAML, or a campaign directory

options:
  -h, --help            show this help message and exit
  --set KEY=VALUE
  --reason REASON
  --candidate CANDIDATE
                        shadow: the candidate to run alongside the active
                        version
  --split SPLIT         shadow: benchmark split (default: the config's)
  --publish             status: also (re)write the campaign's active.json

hylo evolve run¶

usage: hylo evolve [-h] [--set KEY=VALUE] [--reason REASON]
                   [--candidate CANDIDATE] [--split SPLIT] [--publish]
                   {run,status,approve,rollback,shadow} target

positional arguments:
  {run,status,approve,rollback,shadow}
  target                evolve config YAML, or a campaign directory

options:
  -h, --help            show this help message and exit
  --set KEY=VALUE
  --reason REASON
  --candidate CANDIDATE
                        shadow: the candidate to run alongside the active
                        version
  --split SPLIT         shadow: benchmark split (default: the config's)
  --publish             status: also (re)write the campaign's active.json

hylo evolve status¶

usage: hylo evolve [-h] [--set KEY=VALUE] [--reason REASON]
                   [--candidate CANDIDATE] [--split SPLIT] [--publish]
                   {run,status,approve,rollback,shadow} target

positional arguments:
  {run,status,approve,rollback,shadow}
  target                evolve config YAML, or a campaign directory

options:
  -h, --help            show this help message and exit
  --set KEY=VALUE
  --reason REASON
  --candidate CANDIDATE
                        shadow: the candidate to run alongside the active
                        version
  --split SPLIT         shadow: benchmark split (default: the config's)
  --publish             status: also (re)write the campaign's active.json

hylo evolve approve¶

usage: hylo evolve [-h] [--set KEY=VALUE] [--reason REASON]
                   [--candidate CANDIDATE] [--split SPLIT] [--publish]
                   {run,status,approve,rollback,shadow} target

positional arguments:
  {run,status,approve,rollback,shadow}
  target                evolve config YAML, or a campaign directory

options:
  -h, --help            show this help message and exit
  --set KEY=VALUE
  --reason REASON
  --candidate CANDIDATE
                        shadow: the candidate to run alongside the active
                        version
  --split SPLIT         shadow: benchmark split (default: the config's)
  --publish             status: also (re)write the campaign's active.json

hylo evolve rollback¶

usage: hylo evolve [-h] [--set KEY=VALUE] [--reason REASON]
                   [--candidate CANDIDATE] [--split SPLIT] [--publish]
                   {run,status,approve,rollback,shadow} target

positional arguments:
  {run,status,approve,rollback,shadow}
  target                evolve config YAML, or a campaign directory

options:
  -h, --help            show this help message and exit
  --set KEY=VALUE
  --reason REASON
  --candidate CANDIDATE
                        shadow: the candidate to run alongside the active
                        version
  --split SPLIT         shadow: benchmark split (default: the config's)
  --publish             status: also (re)write the campaign's active.json

hylo evolve shadow¶

usage: hylo evolve [-h] [--set KEY=VALUE] [--reason REASON]
                   [--candidate CANDIDATE] [--split SPLIT] [--publish]
                   {run,status,approve,rollback,shadow} target

positional arguments:
  {run,status,approve,rollback,shadow}
  target                evolve config YAML, or a campaign directory

options:
  -h, --help            show this help message and exit
  --set KEY=VALUE
  --reason REASON
  --candidate CANDIDATE
                        shadow: the candidate to run alongside the active
                        version
  --split SPLIT         shadow: benchmark split (default: the config's)
  --publish             status: also (re)write the campaign's active.json

hylo ingest¶

usage: hylo ingest [-h] [--python PYTHON] spec

positional arguments:
  spec             JSON: {"source": {"type", "params"}, "name", "licence",
                   "out", "image_every", "assume_success"}

options:
  -h, --help       show this help message and exit
  --python PYTHON  interpreter whose venv has the source's dependencies

hylo label¶

usage: hylo label [-h] --judge JUDGE [--judge-type JUDGE_TYPE]
                  [--threshold THRESHOLD]
                  run

positional arguments:
  run

options:
  -h, --help            show this help message and exit
  --judge JUDGE         the judge's artifact (directory or store id)
  --judge-type JUDGE_TYPE
  --threshold THRESHOLD

hylo learn¶

usage: hylo learn [-h] [--python PYTHON] [--timeout TIMEOUT] job

positional arguments:
  job

options:
  -h, --help         show this help message and exit
  --python PYTHON    interpreter to run the learner with (its venv); default:
                     in this process
  --timeout TIMEOUT

hylo playground¶

usage: hylo-playground [-h] [--root ROOT] [--repo REPO] [--host HOST]
                       [--port PORT] [--token TOKEN] [--judge JUDGE]
                       [--workcell NAME=URL[#TOKEN]]
                       [--policy NAME=WS_URL[#TOKEN]]
                       [--role-token ROLE=TOKEN]

options:
  -h, --help            show this help message and exit
  --root ROOT           runs directory (relative to --repo)
  --repo REPO           repository root (for examples/ and job working
                        directory)
  --host HOST
  --port PORT
  --token TOKEN         require this token on every API call (x-token header
                        or ?token=)
  --judge JUDGE         success-judge artifact used for progress curves
  --workcell NAME=URL[#TOKEN]
                        a workcell service
  --policy NAME=WS_URL[#TOKEN]
                        a policy server endpoint
  --role-token ROLE=TOKEN
                        viewer / operator / approver tokens (none given: the
                        local user has every role)

hylo plugin¶

usage: hylo plugin [-h] [--dir DIR] [--params PARAMS]
                   [--experiment EXPERIMENT]
                   {new,check}
                   {guard,gate_test,learner,online_learner,datasource,judge,generator,policy,agent}
                   name

positional arguments:
  {new,check}
  {guard,gate_test,learner,online_learner,datasource,judge,generator,policy,agent}
  name                  plugin name (new) or registered name / module:attr
                        (check)

options:
  -h, --help            show this help message and exit
  --dir DIR             new: where to create the package
  --params PARAMS       check: constructor params as JSON
  --experiment EXPERIMENT
                        check: the experiment config to check on (default:
                        MuJoCo planar reach if installed, else the test
                        double)

hylo plugin new¶

usage: hylo plugin [-h] [--dir DIR] [--params PARAMS]
                   [--experiment EXPERIMENT]
                   {new,check}
                   {guard,gate_test,learner,online_learner,datasource,judge,generator,policy,agent}
                   name

positional arguments:
  {new,check}
  {guard,gate_test,learner,online_learner,datasource,judge,generator,policy,agent}
  name                  plugin name (new) or registered name / module:attr
                        (check)

options:
  -h, --help            show this help message and exit
  --dir DIR             new: where to create the package
  --params PARAMS       check: constructor params as JSON
  --experiment EXPERIMENT
                        check: the experiment config to check on (default:
                        MuJoCo planar reach if installed, else the test
                        double)

hylo plugin check¶

usage: hylo plugin [-h] [--dir DIR] [--params PARAMS]
                   [--experiment EXPERIMENT]
                   {new,check}
                   {guard,gate_test,learner,online_learner,datasource,judge,generator,policy,agent}
                   name

positional arguments:
  {new,check}
  {guard,gate_test,learner,online_learner,datasource,judge,generator,policy,agent}
  name                  plugin name (new) or registered name / module:attr
                        (check)

options:
  -h, --help            show this help message and exit
  --dir DIR             new: where to create the package
  --params PARAMS       check: constructor params as JSON
  --experiment EXPERIMENT
                        check: the experiment config to check on (default:
                        MuJoCo planar reach if installed, else the test
                        double)

hylo plugins¶

usage: hylo plugins [-h] [--all] [--json]

options:
  -h, --help  show this help message and exit
  --all       include the test doubles (testing.*)
  --json

hylo profile¶

usage: hylo profile [-h] {show,set-runtime,remove-runtime} ...

Execution profiles (hylo.profile/v0.1): where components run on this machine,
kept out of experiment configs.

positional arguments:
  {show,set-runtime,remove-runtime}
    show                print the profile and where it is
    set-runtime         add or replace a runtime

options:
  -h, --help            show this help message and exit

hylo profile show¶

usage: hylo profile show [-h]

options:
  -h, --help  show this help message and exit

hylo profile set-runtime¶

usage: hylo profile set-runtime [-h] --python PYTHON [--env KEY=VALUE] name

positional arguments:
  name

options:
  -h, --help       show this help message and exit
  --python PYTHON
  --env KEY=VALUE

hylo profile remove-runtime¶

usage: hylo profile remove-runtime [-h] name

positional arguments:
  name

options:
  -h, --help  show this help message and exit

hylo run¶

usage: hylo run [-h] [--split SPLIT] [--output OUTPUT] [--set KEY=VALUE]
                config

positional arguments:
  config

options:
  -h, --help       show this help message and exit
  --split SPLIT
  --output OUTPUT
  --set KEY=VALUE  dotted-path override, e.g. --set
                   benchmark.params.suite=libero_goal --set workers=16

hylo schema¶

usage: hylo schema [-h]
                   [{agent-spec,benchmark,candidate,env-spec,experiment,memory-item,task}]

positional arguments:
  {agent-spec,benchmark,candidate,env-spec,experiment,memory-item,task}

options:
  -h, --help            show this help message and exit

hylo schema agent-spec¶

usage: hylo schema [-h]
                   [{agent-spec,benchmark,candidate,env-spec,experiment,memory-item,task}]

positional arguments:
  {agent-spec,benchmark,candidate,env-spec,experiment,memory-item,task}

options:
  -h, --help            show this help message and exit

hylo schema benchmark¶

usage: hylo schema [-h]
                   [{agent-spec,benchmark,candidate,env-spec,experiment,memory-item,task}]

positional arguments:
  {agent-spec,benchmark,candidate,env-spec,experiment,memory-item,task}

options:
  -h, --help            show this help message and exit

hylo schema candidate¶

usage: hylo schema [-h]
                   [{agent-spec,benchmark,candidate,env-spec,experiment,memory-item,task}]

positional arguments:
  {agent-spec,benchmark,candidate,env-spec,experiment,memory-item,task}

options:
  -h, --help            show this help message and exit

hylo schema env-spec¶

usage: hylo schema [-h]
                   [{agent-spec,benchmark,candidate,env-spec,experiment,memory-item,task}]

positional arguments:
  {agent-spec,benchmark,candidate,env-spec,experiment,memory-item,task}

options:
  -h, --help            show this help message and exit

hylo schema experiment¶

usage: hylo schema [-h]
                   [{agent-spec,benchmark,candidate,env-spec,experiment,memory-item,task}]

positional arguments:
  {agent-spec,benchmark,candidate,env-spec,experiment,memory-item,task}

options:
  -h, --help            show this help message and exit

hylo schema memory-item¶

usage: hylo schema [-h]
                   [{agent-spec,benchmark,candidate,env-spec,experiment,memory-item,task}]

positional arguments:
  {agent-spec,benchmark,candidate,env-spec,experiment,memory-item,task}

options:
  -h, --help            show this help message and exit

hylo schema task¶

usage: hylo schema [-h]
                   [{agent-spec,benchmark,candidate,env-spec,experiment,memory-item,task}]

positional arguments:
  {agent-spec,benchmark,candidate,env-spec,experiment,memory-item,task}

options:
  -h, --help            show this help message and exit

hylo serve¶

usage: hylo serve [-h] {policy,workcell} ...

positional arguments:
  {policy,workcell}
    policy           serve an agent over /wc and /openpi
    workcell         run episodes next to a robot / simulator with a remote
                     policy

options:
  -h, --help         show this help message and exit

also: hylo serve env|agent ... serves one environment or agent plugin over
WebSocket (hylo serve env --help)

hylo serve policy¶

usage: hylo serve policy [-h]
                         (--agent AGENT | --config CONFIG | --campaign CAMPAIGN)
                         [--host HOST] [--port PORT] [--token TOKEN]
                         [--openpi-inputs OPENPI_INPUTS]

options:
  -h, --help            show this help message and exit
  --agent AGENT         agent spec as JSON: {"type": ..., "params": {...}}
  --config CONFIG       experiment config whose agent to serve
  --campaign CAMPAIGN   campaign directory: serve its active version,
                        following promotions
  --host HOST
  --port PORT
  --token TOKEN         require 'Authorization: Bearer <token>' (or openpi's
                        'Api-Key <token>')
  --openpi-inputs OPENPI_INPUTS
                        preset name or JSON mapping of openpi keys to
                        observation fields

hylo serve workcell¶

usage: hylo serve workcell [-h] --config CONFIG [--host HOST] [--port PORT]
                           [--token TOKEN]

options:
  -h, --help       show this help message and exit
  --config CONFIG  workcell config (YAML or JSON), see hylo.serve.workcell
  --host HOST
  --port PORT
  --token TOKEN

hylo skills¶

usage: hylo evolve skills [-h] --out OUT [--tags [TAGS ...]] [--env ENV]
                          [--prefix PREFIX]
                          archive

positional arguments:
  archive            campaign directory (with archive.jsonl) or an
                     archive.jsonl file

options:
  -h, --help         show this help message and exit
  --out OUT          skill library directory
  --tags [TAGS ...]
  --env ENV
  --prefix PREFIX

hylo store¶

usage: hylo store [-h] [--root ROOT]
                  {init,where,index,ls,show,ref,rm,push,pull,adopt} ...

the run and artifact store: ids, references, deletion protection, sync between
machines

positional arguments:
  {init,where,index,ls,show,ref,rm,push,pull,adopt}
    init                make PATH this machine's store (recorded in the
                        profile) and index it
    where               print the store directory
    index               rebuild the index
    ls                  list runs and artifacts
    show                an entry, its path and what refers to it
    ref                 the id of a run or artifact directory
    rm                  delete a run or artifact (refused while something
                        refers to it)
    push                copy runs and artifacts from here to another store
    pull                copy runs and artifacts from another store to here
    adopt               seal a directory built before artifacts had manifests
                        (RFC-0004)

options:
  -h, --help            show this help message and exit
  --root ROOT           the store directory (default: this machine's profile,
                        $HYLO_STORE, ./runs)

hylo store init¶

usage: hylo store init [-h] path

positional arguments:
  path

options:
  -h, --help  show this help message and exit

hylo store where¶

usage: hylo store where [-h]

options:
  -h, --help  show this help message and exit

hylo store index¶

usage: hylo store index [-h]

options:
  -h, --help  show this help message and exit

hylo store ls¶

usage: hylo store ls [-h] [--kind {run,artifact}] [--name NAME] [--json]

options:
  -h, --help            show this help message and exit
  --kind {run,artifact}
  --name NAME
  --json

hylo store show¶

usage: hylo store show [-h] ref

positional arguments:
  ref

options:
  -h, --help  show this help message and exit

hylo store ref¶

usage: hylo store ref [-h] path

positional arguments:
  path

options:
  -h, --help  show this help message and exit

hylo store rm¶

usage: hylo store rm [-h] [--force] [--reason REASON] ref

positional arguments:
  ref

options:
  -h, --help       show this help message and exit
  --force
  --reason REASON

hylo store push¶

usage: hylo store push [-h] [--with-sources] [--dry-run]
                       [--remote-command REMOTE_COMMAND]
                       location [ids ...]

positional arguments:
  location              PATH or HOST:PATH
  ids                   what to copy (default: everything)

options:
  -h, --help            show this help message and exit
  --with-sources        also what the selected artifacts were built from
  --dry-run
  --remote-command REMOTE_COMMAND
                        the hylo command on the other machine

hylo store pull¶

usage: hylo store pull [-h] [--with-sources] [--dry-run]
                       [--remote-command REMOTE_COMMAND]
                       location [ids ...]

positional arguments:
  location              PATH or HOST:PATH
  ids                   what to copy (default: everything)

options:
  -h, --help            show this help message and exit
  --with-sources        also what the selected artifacts were built from
  --dry-run
  --remote-command REMOTE_COMMAND
                        the hylo command on the other machine

hylo store adopt¶

usage: hylo store adopt [-h] --kind KIND --role
                        {behaviour,instrument,proposal,data} [--name NAME]
                        [--source RUN_DIR|run:ID]
                        path

positional arguments:
  path

options:
  -h, --help            show this help message and exit
  --kind KIND
  --role {behaviour,instrument,proposal,data}
  --name NAME
  --source RUN_DIR|run:ID
                        a run it was built from (repeat); without any, the
                        provenance is recorded as unknown

hylo trace¶

usage: hylo trace [-h] run_dir [episode]

positional arguments:
  run_dir
  episode

options:
  -h, --help  show this help message and exit