Documentation CLI 0.1.1 · development llms.txt

coldctl agent sync

Send allowlisted metadata to Cloud.

ImplementedCloud metadata upload

Syntax

USAGE

coldctl agent sync [OPTIONS]

Arguments & options

Option	Description / default
`--cloud-url <CLOUD_URL>`	Cloud origin, for example https://your-console.example.com
`--data-dir <PATH>`	Override the OS application data directory
`--token-env <TOKEN_ENV>`	Environment variable containing a lifecycle-scoped Cloud token [default: COLDCTL_CLOUD_TOKEN]
`--dry-run`	Print the exact metadata payload without network access or token lookup
`--allow-local-http`	Permit HTTP to a numeric loopback address for local testing only
`--watch`	Keep synchronizing until stopped; run under your service manager
`--interval-seconds <INTERVAL_SECONDS>`	Seconds between successful uploads in watch mode (30..86400) [default: 300]
`-h, --help`	Print help

Examples

Replace configuration names, paths and JOB_ID with values from your installation. Examples are not executed by this page.

CLI

coldctl agent sync --dry-run
coldctl agent sync --cloud-url https://console.example.com

CLI

coldctl agent sync --cloud-url https://console.example.com --watch --interval-seconds 300

Operational notes

Create a lifecycle token in Cloud Settings and supply it through COLDCTL_CLOUD_TOKEN, or choose its environment-variable name with --token-env. Dry-run prints the exact payload without token lookup or network access. HTTPS is required; explicit --allow-local-http permits numeric loopback only. Redirects are rejected. Sync is one-way; --watch enables background uploads.

Watch runs until stopped; supervise it separately from archival. Retries back off from 30 seconds to one hour and persist across restarts. Each attempt collects fresh metadata; intermediate states are coalesced. Schema-v2 uses up to 1,024 pages of 100 records / 40 KiB / 24,000 UTF-16 units each; commit publishes the complete generation. Upgrade Cloud first. Dry-run emits the page array. Restart after changing token environment variables. Use agent sync-status to inspect progress.

Output, placeholders & global flags

View exact CLI help

HELP OUTPUT

Explicitly upload allowlisted lifecycle metadata to your Cloud workspace

Usage: coldctl agent sync [OPTIONS]

Options:
      --cloud-url <CLOUD_URL>
          Cloud origin, for example https://your-console.example.com
      --data-dir <PATH>
          Override the OS application data directory
      --token-env <TOKEN_ENV>
          Environment variable containing a lifecycle-scoped Cloud token [default: COLDCTL_CLOUD_TOKEN]
      --dry-run
          Print the exact metadata payload without network access or token lookup
      --allow-local-http
          Permit HTTP to a numeric loopback address for local testing only
      --watch
          Keep synchronizing until stopped; run under your service manager
      --interval-seconds <INTERVAL_SECONDS>
          Seconds between successful uploads in watch mode (30..86400) [default: 300]
  -h, --help
          Print help