<!-- source: https://cli.dreamlake.ai/jobs @ 0.134.0 99837ab -->

# External job tracking

`dl jobs` tracks work launched by another tool. It requires CLI 0.55.0 or later
and a compatible Jobs API. Availability depends on both deployments; this source
change does not establish production availability. CLI 0.54.1 and earlier do not
include these commands. Registration does not launch
work, discover processes, collect output, or grant runner control. Existing
[`dl run` and `dl runs`](/runs.md) remain the managed execution interface.

## Register external work

Find the exact host ID with `dl hosts list --namespace geyang --json`.
`--host` accepts only the lowercase 24-character hexadecimal `Host.id`, not a
host name, enrollment ID, or the illustrative `h_...` IDs in design examples.
The selected host must be owned and accessible in the selected namespace.

```bash cli-help="jobs register"
dl jobs register --namespace geyang --name train-baseline \
  --host 0123456789abcdef01234567 --request-id train-baseline-01
```

Use `--namespace` to select an organization or another authorized namespace;
otherwise the CLI resolves your current user's namespace. Registration requires
`--request-id`. Repeating the same ID, name, host, and namespace returns the same
job with `alreadyRegistered: true`; changing the payload conflicts. Retain this
ID after an uncertain request. Names are trimmed and limited to 200 characters
without control characters. Request IDs allow 1–128 letters, digits, underscores,
dots, colons, and hyphens. Job IDs are also exact lowercase 24-character hex IDs.

## Report an observation

Run these commands only after the external runner has observed the stated
condition. `cancelled` reports cancellation performed elsewhere; it does not stop
a process. A successful report command exits zero even when reporting `failed`.

```bash cli-help="jobs report"
dl jobs report 89abcdef0123456789abcdef --namespace geyang --state running
dl jobs report 89abcdef0123456789abcdef --namespace geyang \
  --state succeeded --exit-code 0
dl jobs report fedcba9876543210fedcba98 --namespace geyang \
  --state failed --exit-code 7 --message 'Training process exited with an error'
```

Each report sends a UTC observation timestamp, defaulting to the time the command
starts. For retryable automation, explicitly set `--reported-at` and reuse the
same timestamp and payload. On failure, the CLI returns the attempted timestamp
so an uncertain write can be retried exactly. The API rejects older observations,
changed payloads at an existing timestamp, and timestamps more than 60 seconds
in the future. Seconds or three fractional digits are accepted, always with `Z`.

```bash
dl jobs report 89abcdef0123456789abcdef --namespace geyang \
  --state running --reported-at 2026-10-12T12:00:00.000Z --json
```

Terminal reports cannot reopen a job or change its terminal state or exit code.
Exit codes are optional signed 32-bit integers for terminal reports: `succeeded`
requires zero when supplied, `failed` requires nonzero, and `cancelled` allows
any value. Messages are explicit text of at most 2000 characters, without NUL.
Omitted optional fields are omitted from the HTTP request, not sent as null.
No program output is automatically captured or indexed.

## Read reported state and age

```bash cli-help="jobs list"
dl jobs list --namespace geyang
dl jobs list --namespace geyang --host 0123456789abcdef01234567 --state running
dl jobs list --namespace geyang --page 2 --page-size 50 --json
```

Lists return one page, with `page`, `pageSize`, `total`, `totalPages`, and `readAt`.
Text output shows the page count and prompts for the next page when present.
`--page` accepts 1–10000; `--page-size` accepts 1–100 and defaults to 50. Host and
state filters remain explicit. Access and namespace failures are errors, never
substituted with an empty list.

```bash cli-help="jobs status"
dl jobs status 89abcdef0123456789abcdef --namespace geyang
dl jobs status 89abcdef0123456789abcdef --namespace geyang --json
```

Text labels the **reported state**, last report age, and freshness. Registration
alone has state `registered`, no report timestamp or age, and execution state
“not yet reported.” An old `running` observation remains reported `running`; the
CLI never infers failure or confirms live execution from age. Terminal states
are also historical observations.

JSON preserves the full API envelope and timestamps: `reportedAt` is the caller's
observation time, `receivedAt` is server receipt time, and `reportAgeSeconds` is
computed by the API from the observation timestamp, rounded down and clamped to
zero. `reportFreshness` is `missing`, `fresh` through 300 seconds, or `stale`.
`processVerified` is always false, even for fresh reports. Registration receipts
also include `alreadyRegistered`. Error JSON includes an error message and safe
API code/status when available; registration/report failures include retry
identity. Missing or inaccessible jobs are reported without claiming which case
applies.

General Jobs logs, cancellation control, submission, waiting, artifacts, and
lifecycle commands are not implemented by this tracking interface. Use existing
managed-run commands only for runs actually submitted through that interface.
