Skip to main content

envloop-cli: EnvLoop CLI and Python SDK

Install the public client to run agent Jobs, inspect Trials, manage training and checkpoints, and deploy or call inference endpoints. The el and envloop commands are equivalent. The Python import package is envloop.

Release compatibility

This page describes the current client source. Published 1.33.0 includes runner list|get|create|update|delete, replacing the list|register commands in 1.32.0. The enhancements below are not in published 1.33.0 and await a new release. Check your installed el --version and el COMMAND --help before following an example; the source package version alone does not identify unreleased features.

Unreleased source enhancement Published 1.33.0
Explicit --json for el runner get|create|update|delete These commands already output JSON; omit --json
el data upload harbor --update-digests not available; set [[tasks]] digest values by hand
el trial artifact download TRIAL_ID --output DIRECTORY positional DIRECTORY only

Execution also requires a matching platform, project permissions and published Runners; package installation alone does not establish those prerequisites. See the PyPI release history for published versions.

Profile v4 requires platform support from EnvPlatform #1489. Running a v6 Runner in a Sandbox also requires the bootstrap fix in EnvPlatform #1490. Platform 1.71.0 contains neither change: upgrading the CLI alone does not enable these features on that server version. Existing historical Profile formats remain available while waiting for a compatible platform release.

Install

envloop-cli requires Python 3.12 or later; an existing compatible interpreter can be reused. The following uv example uses Python 3.12:

uv tool install --python 3.12 envloop-cli
el --version    # upgrade later with: uv tool upgrade --python 3.12 envloop-cli
el --help

To use the Python SDK, install the package into a Python 3.12+ virtual environment:

uv venv --python 3.12
uv pip install --upgrade envloop-cli
# or, with an existing Python 3.12 interpreter:
python3.12 -m pip install --upgrade envloop-cli

Every installation includes Jobs, Trials, training, logs, inference calls, Data resources, checkpoints and RSI Loop controls. Check that the SDK can be imported:

python -c 'from envloop import Client; print("EnvLoop SDK ready")'

When you see EnvLoop SDK ready, continue to Connect. This check imports the client without creating a Job. Submit training through client.training_jobs; follow the managed training guide.

Install the client in your Python environment; the platform provides the execution resources.

Optional features

One envloop-cli wheel and source archive contain all feature code. Extras add dependencies only:

python -m pip install envloop-cli
python -m pip install "envloop-cli[data]"
python -m pip install "envloop-cli[data,experiment,rsi-loop]"

Every installation includes the existing Job, Trial, Data and RSI Loop commands, and every --help works without extras. The bare installation and default, experiment, rsi-loop groups have no runtime dependencies. data adds envloop-envhub==1.23.0 for ANS parsing, file-manifest publication and verified directory downloads. Other Data API operations use the bundled client implementation. A command that needs the missing ANS dependency stops with FEATURE_NOT_INSTALLED and the envloop-cli[data] installation instruction.

Feature modules load lazily. Default imports, help and experiment operations do not require EnvHub or certifi. Only the single envloop-cli distribution owns the el / envloop scripts. The examples below require an authorized matching platform; installation does not grant permissions.

Versions 1.23.0 and 1.24.0 on PyPI depend on feature packages that were never published: their data extra cannot be installed and the DATA command group is empty. They also install a separate envloop-cli-experiment package that shares files with this release. Remove both before installing; uninstalling envloop-cli-experiment after an upgrade deletes files the client needs and leads to FEATURE_NOT_INSTALLED, which the same commands repair:

python -m pip uninstall -y envloop-cli envloop-cli-experiment
python -m pip install "envloop-cli[data]"

Connect

Use an authorized EnvLoop account and project. Browser authorization:

el auth login
el auth status --check

For an existing project API key, use the masked configuration wizard:

el auth config
el auth status --check

CI can read credentials from ENVLOOP_API_KEY and connection settings from ENVLOOP_BASE_URL, ENVLOOP_WORKSPACE_ID and ENVLOOP_PROJECT_ID. Keep keys in your secret manager. Public API access is scoped to the authorized project.

Credentials and settings live in ~/.envloop (override with an absolute ENVLOOP_HOME). On POSIX the directory must be private and owned by you. Use the default path when the optional environment variable is unset:

mkdir -p "${ENVLOOP_HOME:-$HOME/.envloop}"
chmod 700 "${ENVLOOP_HOME:-$HOME/.envloop}"

An insecure directory causes el to fail with CONFIG_INSECURE_PATH.

Errors

Errors go to stderr as an error code, a short explanation and the applicable HTTP status, without a Hint. Interactive terminals use a red heading and a dim HTTP status. Redirected output, pipes, TERM=dumb, or a nonempty NO_COLOR disable color. --json stdout remains JSON.

Error: PROFILE_NOT_FOUND
  The Profile was not found or is not readable in the current scope.
  Request: GET /v1/profiles/YWNtZS9leGFtcGxl
  HTTP 404

A 404 also names the API request that returned it, without query; resource names in the path are base64url-encoded. An API key works only in the workspace and project it was issued for; selecting another one returns API_KEY_SCOPE_MISMATCH (HTTP 403), whose message names both scopes.

Explore your project

el job list --limit 5
el job list --type train --limit 5
el trial list --limit 5
el trial list --type train --job-id JOB_ID
el checkpoint list --limit 5
el job list --type inference

Query a returned Job ID with el job get JOB_ID and el job result JOB_ID. Trial commands use el trial, for example el trial artifact list TRIAL_ID. Use each command's --help for options.

For the Python SDK:

from envloop import Client

with Client.remote() as client:
    print(client.jobs.list(limit=5))
    print(client.trials.list(type="train", limit=5))

Submitting work, training a model or starting inference can allocate billable resources. Follow the task-specific guide and retain the outputs you need before cleaning up temporary resources.

Sandbox jobs

After el auth login, you may reuse an existing EnvPlatform Profile as an optional preset. It uses the current login and project permissions. Submit its published name and optional ANS input bindings or declared parameters:

el job submit --type sandbox --profile team/report@1 --input report=ARTIFACT_URI --params Mode=Summary --max-cost-usd 3

The platform resolves and freezes the Runner and inputs, and manages any model service declared by the Profile. No local script, Dataset Task wrapper or Runner argument is required. Use a published Artifact URI in place of ARTIFACT_URI.

A Dataset input selects its config and split with --input-config NAME=CONFIG and --input-split NAME=SPLIT; when only one Dataset is bound, --config and --split are shorthands. A Dataset URI alone uses the default config and the train split:

el job submit --type train --profile team/sft@3 \
  --input train_dataset=envloop://datasets/envloop/pev@1.0.4 --input-split train_dataset=train-1 \
  --input eval_dataset=envloop://datasets/envloop/pev@1.0.4 --input-split eval_dataset=validation

--profile and --spec are mutually exclusive. Named Profile parameter names retain their case and duplicates are rejected.

With a matching platform and a published envloop/base ANS Runner, submit a Sandbox Job without a Dataset:

el job submit --type sandbox --runner base --command 'python --version'
el job submit --type sandbox --runner base --image python:3.11 --wait
el job list --type sandbox
el job log JOB_ID --follow

The platform resolves base to the registered envloop/base@main source ref and freezes its immutable Revision. The Sandbox image defaults to the registered Runner image; --image accepts an image name, tag or digest. The execution provider is configured by the server. Job logs retain the actual captured output and collection metadata. Failures include a code, readable explanation, HTTP status when available, and recovery guidance without echoing arbitrary response bodies or credentials.

Existing installations

This distribution provides both the CLI and the envloop import package. Use a fresh environment if you previously installed the separate source distribution named envloop, so two distributions do not own the same Python module files. Existing client configuration is reused; installing a package does not change your account permissions or move remote resources. Check el --help when upgrading because command groups may differ from your earlier installation.

Documentation

Submit managed training

Prepare a recipe-supported REQUEST.json using the SFT quickstart. Training uses billable resources. Check your project permissions, balance and data format, then submit once:

el job submit --type train --spec REQUEST.json
el job get JOB_ID
el job log JOB_ID --follow
el job result JOB_ID
el checkpoint list --job-id JOB_ID

job submit --spec reads the complete Job specification JSON file for Train or Inference. The former job submit --file option is removed; the JSON payload is unchanged.

Replace JOB_ID with the receipt's value. Read the training status and logs, then find the registered checkpoint after success. Ctrl-C ends log reading; to stop training, use el job stop JOB_ID and check its state and resource cleanup. See Checkpoints to download or delete saved weights.

The built-in SFT recipe does not support custom loss, RL or optimizer-state resume. For an older interactive training script, follow the managed training migration.

Run a GPU Runner

Choose a published Runner readable in your project. Save this request as gpu-run.json, replacing FULL_COMMIT with the full Revision from el runner list --json:

{
  "request_id": "gpu-run-001",
  "trials": [
    {"name": "first", "spec": {"runner": "envloop/bash@FULL_COMMIT", "resources": {"gpu_type": "H100", "gpus": 4}, "timeout_seconds": 600}},
    {"name": "second", "spec": {"runner": "envloop/bash@FULL_COMMIT", "resources": {"gpu_type": "H100", "gpus": 4}, "timeout_seconds": 600}}
  ]
}
el job submit --type train --spec gpu-run.json
el job get JOB_ID
el job log JOB_ID --follow
el job result JOB_ID

Replace JOB_ID with the returned value. The example has two independent Trials, each requesting four H100 GPUs: concurrent execution needs eight GPUs. Capacity and budget determine actual concurrency. Startup and execution are billable; check the Runner requirements, project training.run permission, and applicable prices and balance in your authorized Console account first. Reduce the Trial or GPU count when your program supports a smaller first run. The usage guide explains resource observations.

The request file does not depend on GPU shortcut flags. If el job submit --help lists both --trials and --gpu-type, you can instead use the shortcuts in GPU Runner training. Choose one submission method to avoid duplicate runs. The SDK accepts the same dictionary through client.training_jobs.submit(request).

The platform starts the published Revision’s main.sh / main.py using the Runner image; it does not upload local code. An optional command can only supply a declared run_command parameter. If this mode or GPU type is unavailable, contact your project administrator. Use el job stop JOB_ID to stop every Trial, then inspect each Trial’s cleanup_confirmed and download the uploaded artifacts you need.

CLI output uses compact timestamps and highlights statuses and log levels by default on terminals. Use el --no-color job list or append --no-color to a command to disable highlighting, including errors. NO_COLOR=1, TERM=dumb, pipes, and redirected output also disable colors. JSON preserves original values. List and table times are UTC with a UTC label; Job logs retain the recorded timezone and mark lines collected only after the Job ended with (backfilled). Full precision, offsets and the backfilled field are available through --json. el loop live LOOP_ID --follow --json emits complete response frames as NDJSON; Ctrl-C stops reading without stopping the Loop.

Job-bound decision plugins

When the platform and published Runner support Job Profiles, include the authorized profile snapshot in the Train or Inference request's spec. The platform freezes its inputs, recipe and approved plugin pins. This does not select an executor or provider.

For an Inference Job with a bound decision plugin, save the plugin payload as JSON:

el job decision JOB_ID --model WORKSPACE/MODEL --spec payload.json
with Client.remote() as client:
    result = client.decision.evaluate(
        "JOB_ID", model="WORKSPACE/MODEL", payload=payload
    )

Use the exact model returned by the Job. The SDK forwards the payload to the Job's /inference/decision API; the approved plugin validates its business fields. Availability requires matching platform support and approved content in your project.

ANS data and verified downloads

client.data.download_directory(uri, destination) and el data download DATA_ID|URI --output ./content download a complete registered ANS object directory through EnvHub. Datasets require split="lite" / --split lite (the error lists the declared splits); the Dataset version and filenames are preserved. After API authorization the SDK uses GET URLs valid for up to five minutes, verifies file size/SHA-256, and installs the directory atomically. Matching platform support is required.

A compatible server is required. Data uses the permission of the resource it touches: read (for example datasets.read) to query and download, write to publish and upload, delete to retire; a key from el auth login follows your project role. The current login selects the base URL, workspace and project; there is no --env flag. After configuring the Key using el auth config:

el data list --type dataset --json
el data get DATA_ID --json
el data download DATA_ID --file FILE_ID --output ./dataset.tgz --resume --json

Unified ANS CRUD supports Dataset, Runner, Recipe and HF model Checkpoint registrations through el data and client.data. Dataset/Runner/Recipe creation requires a native --manifest and exact --directory; a Recipe may instead be built from a directory holding a committed recipe.toml (envloop.recipe/v2) and entrypoint.sh with el data create --type recipe --directory DIR [--revision REF] (SDK client.data.create(type="recipe", directory=DIR)). For Dataset create/update/upload, --ref (SDK ref) is optional when dataset.namespace, dataset.name and dataset.version are present in the manifest; EnvHub derives the immutable Dataset URI. Other resource types and manifests without that identity still require an explicit ref. Explicit refs remain supported; the platform validates their consistency with the manifest. HF metadata registration uses el data create --type checkpoint --model namespace/model --revision FULL_COMMIT; SDK uses create(kind="checkpoint", model=..., revision=...). HF weights are not downloaded, and artifact imports do not establish Model or Job checkpoint provenance. While native publication runs, create/update repeat the same idempotent request until ready (--timeout, default 3600 s); --no-wait / wait=False returns the pending publishing resource with resume instructions.

el data upload harbor DIR --name NAMESPACE/NAME --version VERSION (SDK client.data.upload(DIR, dataset=..., version=...)) checks the directory before uploading and lists every Task whose [[tasks]] digest in dataset.toml no longer matches its files. After reviewing the Task changes, add --update-digests (SDK update_digests=True) to rewrite only those digest values, using the same Task fingerprint that registration verifies; nothing is written when the digests already match or the directory fails any other check, and the rewrite is reported on stderr (updated_digests in the JSON). A version that was already published stays immutable on the platform: publish changed Tasks under a new version.

el runner create DIRECTORY [--revision FULL_COMMIT|BRANCH|TAG] [--source-ref main] (default --revision main, resolved locally and refused unless the directory matches that commit) publishes a Runner package directory through the same Data API with the manifest built for you, then reads the catalog revision back. el profile create|update|fork ... --secret NAME[=prompt|stdin|env:VAR|file:PATH] stores write-only Secret parameters whose names follow the platform's credential rule or secret_params; values never come from the command line. el setting model-access grant NAMESPACE/NAME --protocol anthropic [--revision FULL_COMMIT] (project Admin) lets a published Runner receive the project's metered model key on Fly Trials; list and revoke GRANT_ID manage grants.

Success follows native storage and original catalog readback and returns an ans_ identity. Update publishes an explicit new revision. Delete checks active and unknown dependencies; Runner deletion covers all revisions. Historical bytes and quota usage remain. Commands default to the current login base URL/workspace/project, with no --env. Both Data grants and the corresponding resource capabilities are required.

Read methods include list/get/files/open/download; client.recipes.list/get queries the original Recipe catalog. Downloads verify size/SHA-256 and refuse existing destinations, symlinks and storage redirects. Large payloads use multipart with stable idempotency keys. Staging pub_ IDs and failure phases support retry; they are not native success. Matching client/server support is required. See the Data reference.

Metadata

Release files for envloop-cli 1.34.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for envloop-cli 1.34.0
File Size Uploaded Provenance Actions
envloop_cli-1.34.0.tar.gz 158.6 kB Without provenance Details for envloop_cli-1.34.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for envloop-cli 1.34.0
File Interpreter ABI Platform Actions
envloop_cli-1.34.0-py3-none-any.whl Python 3 none any Details for envloop_cli-1.34.0-py3-none-any.whl

Total release size: 351.8 kB

Release files / envloop_cli-1.34.0.tar.gz

Download URL envloop_cli-1.34.0.tar.gz
Size 158.6 kB
Tags Source
SHA-256 checksum
How to use checksums
571a2ac3e0cc01d58fcd4bcac3d1ca79ff9c09ecd9fd856590b9df7cc9222270
BLAKE2b-256 checksum
How to use checksums
430c14ebc295ac9a7397b1ebd068b2c277d715d85c77b5f936b91fca7ac67488
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.12.23 {"installer":{"name":"uv","version":"0.12.23","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / envloop_cli-1.34.0-py3-none-any.whl

Download URL envloop_cli-1.34.0-py3-none-any.whl
Size 193.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
31ca443f3b877956feb16c3775342b533b9972d33285ffd7e4c53a9859b5822e
BLAKE2b-256 checksum
How to use checksums
77be5ed53a939713afb2e3fda9abf779d92a67019d2a2aba1331a48bf634dc52
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.12.23 {"installer":{"name":"uv","version":"0.12.23","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for envloop-cli 1.34.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.34.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page