Metadata-Version: 2.5
Name: envloop-cli
Version: 1.14.0
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.11
Requires-Dist: certifi>=2026.10.19
Requires-Dist: tinker==0.34.0
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`.

## Version 1.7

- Use published Runner resource shortcuts for Train Jobs and fixed Checkpoint inputs for Inference Jobs.
- Pass `--json` explicitly to `job submit`; failures retain safe error codes and recovery guidance.
- Submit training through Train Jobs. The retired interactive `envloop.training` interface is removed.

After upgrading, check `el --version` and `el job submit --help`. Execution also
requires a matching platform, project permissions and published Runners; package
installation alone does not establish those prerequisites. See the
[PyPI release history](https://pypi.org/project/envloop-cli/#history) for published versions.

## Install

Use a Python virtual environment:

```bash
python -m pip install --upgrade envloop-cli
el --help
```

The standard installation includes the client dependencies for managed training.
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.

## Connect

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.
  HTTP 404
```

## Explore your project

```bash
el job list --limit 5
el job list --type train --limit 5
el trail list --limit 5
el trail 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 the spelling `trail`, for example
`el trail 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

With a matching platform and a published `envhub/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 list --type sandbox
el job log JOB_ID --follow
```

The platform resolves `base` to the registered `envhub/base@main` source ref and
freezes its immutable Revision. The Sandbox image defaults to `python:3.11`;
`--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

- [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 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](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": "envhub/bash@FULL_COMMIT", "resources": {"gpu_type": "H100", "gpus": 4}, "timeout_sec": 600}},
    {"name": "second", "spec": {"runner": "envhub/bash@FULL_COMMIT", "resources": {"gpu_type": "H100", "gpus": 4}, "timeout_sec": 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 [training prices](https://docs.envloop.ai/pricing) first. Reduce the Trial or GPU count when your program supports a smaller first run.

The request file does not depend on GPU shortcut flags. If `el job submit --help` lists both `--trails` and `--gput-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 times use the local timezone; Job logs retain the recorded timezone, with full precision and offsets available through `--json`.
`el job run live RUN --follow --json` emits complete response frames as NDJSON; Ctrl-C stops reading without stopping the Run.
