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