halton-meter cloud

The halton-meter cloud subgroup manages the optional connection from a local daemon to a Halton Meter Cloud workspace. The daemon ships with cloud.enabled = false; nothing flows to the cloud until you run halton-meter cloud connect and approve the pairing in the browser.

For the conceptual model (what syncs, what doesn't, retention windows) see Halton Meter Cloud overview. For the pairing walk-through see Connect your meter.

Synopsis

$ halton-meter cloud <subcommand> [flags]

cloud connect

Pair this daemon to a workspace. Walks the operator through a one-time code:

$ halton-meter cloud connect
⠇ Requesting pairing code from api.haltonmeter.com…
● Pairing code: WXJ4-9KLM
● Approve at: https://app.haltonmeter.com/connect?code=WXJ4-9KLM
⠇ Waiting for approval… (Ctrl-C to cancel)
✓ Approved — workspace: acme-co
✓ Token written to ~/.halton-meter/cloud-credentials.json (chmod 0600)
✓ [cloud] block in config.toml: enabled=true, base_url=https://api.haltonmeter.com

Cancel a stuck pairing: Ctrl-C cancels the local long-poll. As of v0.2.11, re-running halton-meter cloud connect after a prior pairing has been left in flight cancels the previous handshake on the backend so a re-run can't leave a zombie awaiting approval. The cloud-side pairing code expires on its own 10-minute TTL if neither happens.

cloud disconnect

$ halton-meter cloud disconnect

Disconnect is symmetric to connect:

1. The daemon calls DELETE /v1/daemon/disconnect so the token is unusable immediately even if the local files survive (stolen-laptop case).
2. ~/.halton-meter/cloud-credentials.json and ~/.halton-meter/cloud.key are removed.
3. [cloud].enabled is flipped to false.
4. The cloud_state row in SQLite is cleared.

The local database, the captured row history, and the local report command keep working exactly as before. To re-pair: run cloud connect again. The machine appears as a new device unless you preserved ~/.halton-meter/machine.json (which carries the stable machine_id).

cloud status

$ halton-meter cloud status
● State:           ACTIVE
● Workspace:       acme-co
● Last sync:       3s ago
● Unsynced rows:   0
● Last reconcile:  never
● Last error:      —

$ halton-meter cloud status --json
{ "state": "ACTIVE", "paused_reason": null, "last_sync_at": "2026-05-24T13:59:14Z", ... }

The four possible state values are described in Connect your meter: Verifying the link. The decision tree for recovering from a PAUSED state lives in Troubleshooting.

cloud resume

A real recovery command (v0.2.8+), not a no-op.

$ halton-meter cloud resume

Reads the current paused_reason:

• paused_manual: clears the pause immediately.
• paused_unauthorised (401) or paused_forbidden (403): hits GET /v1/daemon/whoami once with the stored token. If 200, clears the pause, the failure counters, and last_error. The daemon unpauses without burning a re-pair.

Use cloud resume first whenever the daemon shows PAUSED. Only fall back to cloud connect if resume reports the token is genuinely invalid. Running cloud connect revokes the existing key, which is wrong when a transient blip or a workspace-side membership flap caused the pause.

cloud sync and the top-level alias halton-meter sync

$ halton-meter cloud sync
● POST /v1/requests/batch  →  200 OK  (1247 rows accepted)

# Top-level alias — same behaviour, shorter to type:
$ halton-meter sync
● POST /v1/requests/batch  →  200 OK  (0 rows pending)

A single drain pass, then exit. CI usage: run halton-meter sync after your test suite so a workspace report fetched immediately afterward includes the run's spend.

cloud reconcile

$ halton-meter cloud reconcile --days 7

Re-costs locally cached rows against the latest pricing matrix and pushes the corrected totals up. --days N selects the window, default 1 (yesterday and today). Use this after a provider price change or after upgrading the daemon to pick up new pricing-table coverage.

Privacy

The cloud upload posture is set by a preset (minimal | standard | full) plus per-field overrides and per-project rules. The default is standard with source_workdir = false. The high-leak field (absolute filesystem paths) is off by default.

$ halton-meter cloud privacy show
● Preset:  standard
● Body sync:  disabled
● Overrides:  source_workdir=false (preset default)
● Per-project: none

$ halton-meter cloud privacy set preset minimal
$ halton-meter cloud privacy set field.source_workdir true     # override one field
$ halton-meter cloud privacy set upload false --project secret-client
$ halton-meter cloud privacy set bodies.enabled true            # opt in to body sync globally
$ halton-meter cloud privacy set bodies.upload false --project secret-client

Targets accepted by privacy set:

• preset <minimal|standard|full>: change the baseline preset.
• field.<name> <true|false>: override a single field (e.g. field.source_workdir, field.prompt_hash). Per-field overrides win over the preset default.
• upload <true|false> [--project SLUG]: flip the metadata-sync master switch, or drop one project's metadata uploads while leaving the global switch on.
• bodies.enabled <true|false>: master switch for body sync (v0.2.2+).
• bodies.upload <true|false> [--project SLUG]: per-project body override.

Body sync (v0.2.2+) is governed by [cloud.bodies], a separate switch from metadata sync. Bodies do not leave the machine until bodies.enabled = true. Per-project overrides win over the global switch: if the global is true but bodies.upload = false --project foo, project foo's bodies stay local.

For the full preset → field mapping see Sync and retention.

Exit codes

See also

• Halton Meter Cloud overview: what cloud adds, what stays local
• Connect your meter: pairing walk-through
• Sync and retention: what syncs, retention windows, opt-in body sync
• Cloud security: token storage, encryption, auth model
• Troubleshooting → PAUSED states