CLI Reference

embedl-hub run start creates a run and prints only its ID to stdout, so shell scripts can capture it (RUN=$(embedl-hub run start --type training)). With --pending the run is created without being started, for work that something else will run later. The embedl-hub log commands push metrics, params, tags, links, artifacts, and dashboards to a run chosen with --run <id>, the EMBEDL_HUB_RUN environment variable, or the workspace default set with embedl-hub use run.

embedl-hub init marks the current directory as a workspace by creating .ehub/, the way git init marks a repository; commands find the nearest one from anywhere inside it, like git finds .git. embedl-hub use saves defaults there, in .ehub/state.yaml: the project, run and batch are personal, so the .ehub/.gitignore written by init keeps the file out of git along with .ehub/batches/. Outside a workspace, use and --use refuse rather than create one; bare embedl-hub use still shows the environment and global values in effect. embedl-hub use project <name> --global saves a project for every directory without its own, in the global config; run and batch have no global scope, so use clear --global clears the project and Hub. Saving a value that a narrower scope overrides warns and names the winner, from use and from --use alike, and use clear reports what is in effect afterwards. embedl-hub use --show-origin prints where the workspace and global settings are stored. embedl-hub status shows the whole setup at once: what bare use and auth print, with the Hub listed once. Both point at the next command to run: run show for the selected run’s status and logs, and batch show when the selected batch holds entries. init -p <name> and show are aliases for use project <name> --global and for status, deprecated in 0.0.9; they warn on stderr and are removed in 0.1.0. The Hub is chosen the same way: EMBEDL_HUB_URL, then use hub <url> in the workspace, then use hub <url> --global, then the public Embedl Hub. embedl-hub auth --api-key - stores a key for the Hub in use (--hub <url> for another one); keys are stored per Hub in the global config and never in a workspace. A key from EMBEDL_HUB_API_KEY is not sent to a Hub set by a workspace unless it is the key stored for that Hub or EMBEDL_HUB_URL names the same Hub; sent to a Hub from the global config, it warns. The 0.0.8 EMBEDL_HUB_API_BASE_URL and the auth flags --base-url, --reset-base-url, --show-base-url and --show-api-key-location are deprecated in 0.0.9 and still work, with a warning, until 0.1.0. A global config or .ehub/use.cfg in the 0.0.8 layout is migrated the first time it is read.

embedl-hub log dashboard <file> uploads a dashboard written by the Python builder’s Dashboard.save(). A run can carry several, so --set-default marks the one its Dashboard tab opens on and --opens-run opens the run itself on it rather than on the run’s details; the second implies the first. Without either the run keeps opening on its details.

embedl-hub run list shows the project’s runs with live state from Embedl Hub, including runs created elsewhere; run list --local shows the runs recorded on this machine, from every project when none is configured. run show prints everything logged on a run — with --commands, also the CLI invocations that touched it on this machine — and run url prints its web address. run update changes a run after the fact: --parent <id> or --no-parent sets or removes its parent link, and --description <text> sets its description (run set-parent is an alias, deprecated in 0.0.9 and removed in 0.1.0). Commands that take a run look it up by its ID alone and use the run’s own project, so they work from any directory; --project only checks that the run is in that project. use run <id> looks the run up the same way and saves its project with it. Queuing into a batch stays offline: each run’s project is looked up when the batch is sent.

For high-frequency logging, embedl-hub batch start creates a local batch; log commands with --batch (or after embedl-hub use batch) queue entries instead of sending them, and embedl-hub batch send delivers everything in consolidated requests. Interrupted sends resume where they left off with only the entries that did not succeed. Entries the hub rejects outright stay pending unless the send is re-run with --skip-rejected, which marks them skipped so the batch can complete.

embedl-hub exec --type <type> <command...> wraps any command in a run: it creates the run, runs the command with EMBEDL_HUB_RUN set so embedl-hub log calls inside it attach to that run, then completes the run from the command’s exit status (zero finishes it, non-zero fails it, a signal kills it), and passes termination signals on to the command so a scheduler can cancel it. A signal arriving when there is no command to pass it to – before it starts, or while the run is being completed – is acted on once the run is settled, and still exits 128 + N rather than reporting anything of its own. These signal statuses are POSIX ones; on Windows a forwarded signal surfaces as an ordinary exit code instead, and the run is completed as failed rather than killed. A command that cannot be launched reports the status a shell reports – 127 when it cannot be found, 126 when it cannot be run – so $? means the same with the wrapper as without it. A script with no #! line still runs, as it does at the prompt; a file the system cannot load and that does not read as text is refused rather than run, so a corrupt file cannot be reported as a finished run. With --use-pending-run RUN_ID no run is created: the pending run named, made earlier with run start --pending and annotated with embedl-hub log, is started as the command starts and completed the same way, so what was recorded before launch and what the command logs end up on one run. It cannot be combined with --type, --name or --parent. The run is found by its ID, and --project only checks that it is in that project, as for every command that takes a run. A run that is not pending, or not in --project, stops the command with exit status 1 whatever --safe says; with --safe an unreachable Hub still runs the command, untracked.

Any inherited EMBEDL_HUB_RUN is dropped, so the command never logs into an unrelated run. A Python command can pick up the run exec made for it with Client.use_context_run(), which reads EMBEDL_HUB_RUN (or, outside exec, the workspace’s run) and logs into that run rather than starting another, binding the run’s own project. When tracking was skipped exec sets EMBEDL_HUB_UNTRACKED instead, and use_context_run() returns None with a warning rather than falling through to the workspace’s run. Wrap the logging that follows in client.safe_log() for the same script to work with and without --safe: logging with no run adopted otherwise raises, and the outage --safe absorbed would reach the command by another route. --safe also exports EMBEDL_HUB_SAFE, which makes the adoption itself tolerant, so a Hub that goes down between starting the run and adopting it warns rather than raising. Completing the run stays with exec, which sets its outcome from the command’s exit status. The command need not be Python – a shell script, a Makefile target or a binary all work – and everything after it is passed through untouched, so its own flags are never read as exec’s. exec exits with the command’s own status (128 + N when signalled), with two exceptions. A cancellation you sent wins, exiting 128 + N even when the command had already finished on its own. And without --safe, a command that succeeded but whose run could not be completed exits 1, so that a lost run record is not reported as a clean finish; a command that failed on its own terms keeps its own status either way. With --safe, a Hub outage costs the run record but still runs the command and still reports its status.

embedl-hub

auth

init

status

use

run

project

hub

batch

clear

run

start

finish

list

show

update

url

exec

log

metric

param

tag

link

artifact

dashboard

batch

start

send

show

list

discard