Metadata-Version: 2.5
Name: envloop-cli
Version: 2.4.2
Summary: EnvLoop CLI and Python SDK for jobs, training, checkpoints and inference
Project-URL: Homepage, https://envloop.ai
Project-URL: Documentation, https://docs.envloop.ai
Project-URL: Repository, https://github.com/EnvLoop/envloop-cli
Project-URL: Issues, https://github.com/EnvLoop/envloop-cli/issues
Project-URL: Agent instructions, https://docs.envloop.ai/skill.md
Requires-Python: >=3.12
Provides-Extra: asset
Requires-Dist: boto3==1.44.3; extra == 'asset'
Requires-Dist: envloop-envhub==2.4.2; extra == 'asset'
Provides-Extra: chat
Requires-Dist: openai==3.55.1; extra == 'chat'
Provides-Extra: default
Provides-Extra: experiment
Provides-Extra: rsi-loop
Description-Content-Type: text/markdown

# 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

Check your installed `el --version` and `el COMMAND --help` when following an
example. Upgrade an older installation with `uv tool upgrade envloop-cli`, or
`python -m pip install --upgrade envloop-cli` in your SDK environment. See the
[PyPI release history](https://pypi.org/project/envloop-cli/#history) for published versions.

Job execution needs project permissions, readable published Runners and a
platform that supports the selected Profile and Runner formats. If the platform
rejects a format, ask your project administrator which published versions it
supports. Use `envloop-cli[chat]` for the Job chat examples below and
`envloop-cli[asset]` for ANS parsing and verified content transfers.

## Install

envloop-cli requires Python 3.12 or later; an existing compatible interpreter can
be reused. The following [uv](https://docs.astral.sh/uv/) example uses Python 3.12:

```bash
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:

```bash
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, Assets, checkpoints and RSI Loop controls.
Check that the SDK can be imported:

```bash
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](https://docs.envloop.ai/training/cli-hello-world).

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:

```bash
python -m pip install envloop-cli
python -m pip install "envloop-cli[asset]"
python -m pip install "envloop-cli[asset,experiment,rsi-loop]"
```

Every installation includes the existing Job, Trial, Assets and RSI Loop commands, and every `--help` works without extras. The bare installation and `default`, `experiment`, `rsi-loop` groups have no runtime dependencies. `asset` adds `envloop-envhub==1.23.0` for ANS parsing and verified content, and `boto3==1.44.3` for direct object storage transfers. Other Assets API operations use the bundled client implementation. A command that needs the missing ANS dependency stops with `FEATURE_NOT_INSTALLED` and the `envloop-cli[asset]` 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 historical `data` extra cannot be installed and their 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:

```bash
python -m pip uninstall -y envloop-cli envloop-cli-experiment
python -m pip install "envloop-cli[asset]"
```

## Connect

For Job-bound chat, install the optional dependency in the same environment:

```bash
python -m pip install "envloop-cli[chat]"
el job chat JOB_ID "Introduce yourself."
el job chat JOB_ID
el job chat JOB_ID "Hello" --json
```

Text answers stream by default. `--json` returns one complete response.
The command uses the configured EnvLoop connection and automatically reads the
Job's model. The `chat` extra uses the official OpenAI Python SDK against EnvLoop;
it does not use an OpenAI account. `/clear` resets terminal history, `/exit` leaves,
and Ctrl+C exits without stopping the Job.

Use an authorized EnvLoop account and project. Browser authorization:

```bash
el auth login
el auth status --check
```

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

```bash
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:

```bash
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.

```text
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

```bash
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:

```python
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:

```bash
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:

```bash
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. Without input overrides, v4/v5
Profiles use a canonical JobSpec after one public schema lookup; explicit values
go in `overrides`, while the platform freezes Profile defaults and inputs.

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

```bash
el job submit --type sandbox --runner base --command 'python --version'
el job submit --type sandbox --runner base --image python:3.11 --wait
el job submit --type sandbox --provider e2b --spec REQUEST.json
el job list --type sandbox
el job log JOB_ID --follow
```

The platform resolves `base` to the newest accessible successfully published `envloop/base` Revision and
freezes its immutable identity. The Sandbox image defaults to the registered Runner image;
`--image` accepts an image name, tag or digest. Bench and Sandbox submissions can request a
platform-enabled provider by name. In a request file, `provider` is a
top-level field alongside `spec` and optional `overrides` in an `envloop.job/v2`
envelope. The `--provider` flag overrides that field and also works with the
named `--profile` shortcut. Omit the selection to use the platform default.
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.

Bench/Sandbox Harbor Recipes accept `--harbor_env docker|process` with a canonical
JobSpec (`spec.schema = "envloop.job/v2"`) or a named `--profile`:

```bash
el job submit --type sandbox --spec REQUEST.json --harbor_env process
```

Omitting the option preserves spec/Profile parameters and the Runner default
(`docker`). An explicit option overrides the file's `harbor_env` parameter;
setting the same key with `--params` is rejected. The option selects Harbor's
task environment; platform execution placement remains server configured.

## 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

- [English documentation](https://docs.envloop.ai/)
- [中文文档](https://docs.envloop.ai/zh-cn/)
- [Installation](https://docs.envloop.ai/cli-install)
- [CLI reference](https://docs.envloop.ai/reference/cli)
- [Training and deployment](https://docs.envloop.ai/training/train-deploy)
- [Agent entry: skill.md](https://docs.envloop.ai/skill.md)

## Submit managed training

Prepare a recipe-supported `REQUEST.json` using the [SFT quickstart](https://docs.envloop.ai/training/quickstart).
Training uses billable resources. Check your project permissions, balance and data format, then submit once:

```bash
el job resolve --spec REQUEST.json --json
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.
`job resolve --spec FILE --json` previews the resolved specification without creating a Job.
Artifact downloads transfer directly from object storage and require `envloop-cli[asset]`; without it they stop with `FEATURE_NOT_INSTALLED` and the install command.

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.
A platform-authorized Train worker publishes its saved checkpoints directly to object storage:

```bash
el checkpoint create --result /output/train-result.json --directory /output --json
```

Install `envloop-cli[asset]` for this operation. The saved `envloop.train-result/v1` descriptors locate the checkpoint directories. The platform supplies producer identity from its worker credential; ordinary project keys cannot claim a Job or Trial. Success returns `durable: true`, `upload_actor: "worker"`, and committed checkpoint receipts with real ANS URIs and manifest SHA-256 values. Local save names and directories are preserved; the published save name is `checkpoint-N` for step N.

See [Checkpoints](https://docs.envloop.ai/training/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](https://docs.envloop.ai/training/sdk-compatibility).

## 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`:

```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}}
  ]
}
```

```bash
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](https://docs.envloop.ai/manage/usage) 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](https://docs.envloop.ai/training/runner). 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:

```bash
el job decision JOB_ID --model WORKSPACE/MODEL --spec payload.json
```

```python
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.

## User Assets and verified downloads

Datasets, Checkpoints, Recipes and Profiles share `list`, `get`, `create`, `update`, `delete`
and `set-visibility`. Every list row is an immutable version. A REF is an opaque resource ID,
a fixed ANS URI supported by that type, or `namespace/name@version`. Recipe/Profile `get` also accepts
bare names or `@latest`, resolved by the platform to the newest accessible successful publication.
Dataset/Checkpoint names require explicit versions; mutation sources remain exact.
`get/create/update` return `{ "asset": RECORD_OR_NULL, "operation": OPERATION_OR_NULL }`.
Records share `asset_id/type/name/version/owner/visibility/acl_revision/status`; type details,
files, model identity and provenance stay in `asset.details`.

```bash
el dataset list --name example/eval --json
el dataset create --file dataset.json --directory ./files --tags 'topic:finance' --wait
el dataset get example/eval@1.0 --json
el dataset file list example/eval@1.0
el dataset download example/eval@1.0 --split test --output ./content
el dataset create --format harbor --directory ./tasks --name example/eval --version 1.0
el dataset registration create example/eval@1.0 --runner envloop/harbor@FULL_COMMIT --wait
el recipe create --directory ./recipe --revision FULL_COMMIT --wait
el checkpoint create --model example/model --revision FULL_MODEL_COMMIT
el checkpoint create --result train-result.json --checkpoint-name checkpoint-100 --directory ./outputs
el profile create --name example/train --version 1.0 --file profile.toml --secret HF_TOKEN=env:HF_TOKEN
el profile update example/train@1.0 --version 2.0 --patch changes.toml
el profile export example/train@2.0 --output ./profile.toml
el dataset set-visibility example/eval@1.0 --visibility internal --expected-acl-revision 3
```

`--file` supplies a complete declaration; `--patch` is Profile update's explicit patch mode.
An update creates a new immutable version owned by the current Project and leaves Profile defaults
and submitted Job references unchanged. Profile default metadata changes use `set-default REF --expected-version V` and do not affect latest selection.
Runner/Recipe references in a Profile may omit the version or use `@latest`; Profile publication retains
those author references. Each new Job freezes the concrete URI, revision, hashes and owner; retries
with the same request ID retain the first choice.
Profile supports private/public; other user content also supports internal. The returned ACL scope
states whether sharing affects a name's versions or one saved record. Every visibility write requires
an explicit `--expected-acl-revision`.

A create/update establishes a unique publication operation and transfers verified bytes. Without
`--wait`, pending results preserve the operation ID and may have `asset: null`; an upload or staging
ID is never substituted for a real asset ID. Use `RESOURCE upload get OPERATION_ID`,
`upload part UPLOAD_ID --number N --file PART`, `upload complete OPERATION_ID` or
`upload abort OPERATION_ID` to inspect/resume that operation. Complete is idempotent and is the
only publication commit; there is no separate upload create command. Failed or timed-out operations
exit nonzero while preserving their safe receipt. Storage credentials are not printed.

Dataset downloads require an explicit split and accept content digest and paired task ID/tree
digest selectors. Directory downloads with an explicit config selector are currently unsupported
by the pinned ANS dependency. Downloads verify manifests, sizes, SHA-256, safe paths and executable bits. Use
`download REF --file-id FILE_ID --output FILE --resume` for a resumable single file. File selection
is separate from `get`; Profile uses a redacted `export` instead of a content download.

Worker checkpoint publication selects exactly one saved descriptor. Multi-save result files require
`--checkpoint-name`. Producer identity comes only from the platform-issued worker credential;
ordinary project keys cannot invent Job/Trial provenance. External HF metadata registration does
not download weights or establish training provenance.

The SDK uses `client.datasets/checkpoints/recipes/profiles` for typed operations and
`client.assets.list/get` for read-only aggregation. Examples:

```python
client.datasets.create(manifest=manifest, files=files, wait=True, tags={"topic": "finance"})
client.datasets.download("example/eval@1.0", "./content", split="test")
client.profiles.update("example/train@1.0", version="2.0", patch={"params": {"seed": 2}})
```

Runner is a platform execution capability under Experiment. Its existing package command remains
`el runner create DIRECTORY --revision FULL_COMMIT`; `runner list --ref REF` and
`runner download REF --output DIR --content-digest SHA256` use the execution domain.
Trial Artifact publication is `el trial artifact create --file manifest.json --directory ./outputs`.
`trial artifact download --ref URI --output DIR --content-digest SHA256` downloads one fixed
ANS directory; `trial artifact download TRIAL_ID --output DIR` downloads all uploaded Trial files.
These execution-owned records are excluded from Assets.


### Update Loop metadata

```bash
el loop update LOOP_ID --spec loop.json
el loop update LOOP_ID --spec '{"schema":"envloop.loop/v1","name":"Carry research"}'
```

```json
{
  "schema": "envloop.loop/v1",
  "name": "Carry research",
  "description": "Compare candidate methods on a fixed evaluation set."
}
```

Supplied fields replace their current values; omitted fields stay unchanged.
Set `"description": ""` to clear it. Pass a JSON file path or a quoted JSON object to `--spec`. Updating metadata needs
`training.run` and keeps the Loop ID, execution settings and recorded research.
Use `client.loops.update(loop_id, spec)` from Python and read the effective `spec`
with `client.loops.get(loop_id)`. See the [Loop guide](https://docs.envloop.ai/guides/rsi-loops#update-metadata).
