CLI

geo-mlops-edge is installed with the edge extra. run is the entry point the service calls; the rest are tools for the person standing at the device asking "why is nothing reaching Central?".

geo-mlops-edge [--version] [-c CONFIG] {run,config,status,sync,queue,models,register} ...

• -c, --config can go before or after the subcommand (geo-mlops-edge run --config … works too). If omitted, the config file lookup order applies.
• status, sync, queue and models do not open the DB directly; they ask the running agent's local API. This avoids a second process touching a live SQLite file. So they also read api.host, api.port and api.token from the config file.

run#

geo-mlops-edge --config /etc/geo-mlops/edge.yaml run

On SIGINT/SIGTERM it cleans up and exits. Exit codes are 0 (stop requested), 3 (restart requested) and 4 (could not open the local API port).

config#

Shows the values actually applied, environment variables included.

geo-mlops-edge -c /etc/geo-mlops/edge.yaml config

{
  "central": {
    "base_url": "https://mlops.example.com",
    "token": "",
    "timeout_s": 10.0,
    "verify_tls": true
  },
  "device": { "id": "edge-bench-01", "location": "bench" },
  "data_dir": "/var/lib/geo-mlops-edge",
  "retention": { "max_bytes": 53687091200, "max_age_days": 30, "free_disk_min_bytes": 5368709120 },
  "...": "..."
}

status#

When a person needs to act, it says so first, in a sentence starting with !! before the JSON. This is actual output from a device whose token was rejected.

!! Central rejected this device's token. Write a new token into the agent's configuration on this machine and restart the service -- command polling has stopped too, so this cannot be fixed remotely.

{
  "device": { "id": "edge-bench-01", "registered": false, "...": "..." },
  "link": {
    "state": "auth_failed",
    "error": "401 invalid or expired edge token (POST https://mlops.example.com/api/v1/edge/telemetry)"
  },
  "sync": { "state": "auth_failed", "...": "..." },
  "...": "..."
}

If the agent is not running, you get this with exit code 3.

no agent is listening on http://127.0.0.1:8600 (is the service running?)

sync#

geo-mlops-edge sync

{ "requested": true }

It only wakes the uploader. If the link is not online, or an upload window or CPU limit is in effect, nothing is sent.

queue#

geo-mlops-edge queue --state failed --limit 20

--state is pending, uploading or failed; --limit defaults to 20. Each item in the result has attempts and last_error, so you can see why it stopped.

models#

geo-mlops-edge models                                          # cache list and active model
geo-mlops-edge models --pull helmet-detector --version-tag 2   # pull and activate

--pull requires --version-tag. The running agent does the pulling, so the agent must be up.

register#

Performs only the registration handshake, without starting the agent. Use it at a new site to confirm the token and address first.

GEO_EDGE_CENTRAL__TOKEN=<device-token> geo-mlops-edge -c /etc/geo-mlops/edge.yaml register --location line-1

{ "id": "edge-bench-01", "status": "ACTIVE" }

Without central.base_url or a token it exits with code 2; if Central rejects it, you get registration failed: … and exit code 4.