Workspace sync

cmdop connect workspace sync pulls the authoritative workspace list from the server and updates ssh_workspaces.json. Use it whenever the server view and your local view fall out of step.

When to sync

Common triggers:

You just signed in via OAuth and want every workspace populated locally.
You were added to a new workspace by a teammate.
A workspace was renamed in the cabinet.
You suspect your local workspace list is stale.
You switched modes (prod ↔ dev) and want the new mode’s workspaces.

How sync works


cmdop connect workspace sync

The CLI:

Calls the REST endpoint with the active OAuth token (sync requires OAuth — API keys do not have permission to enumerate workspaces).
Compares the response to ssh_workspaces.json.
Adds new workspaces, updates RemoteID and LastSyncedAt on existing ones, marks workspaces you have left as inactive (does not delete the API key — you may still want it).
Persists atomically.

API-key workspaces unknown to the server are left untouched — they are local-only by design.

What does not sync

API key secrets — they are not part of the response.
Active workspace pointer — sync does not change which workspace is active.
Server overrides (Workspace.Server) — those are local config and survive sync.

Per-mode sync

CMDOP supports multiple modes (typically prod and dev). Each mode has its own token_<mode>.json and its own conceptual workspace set. Switch modes with:


cmdop --dev connect workspace sync     # syncs against dev server

The flag affects which server is queried and which token is used. The local ssh_workspaces.json interleaves entries from both modes — Workspace.Server distinguishes them.

Reconciling machine ownership

Sync does not move machines between workspaces. If a machine was migrated server-side (e.g. you switched workspaces in the cabinet and the server auto-migrated the record), the agent’s next heartbeat will use the live workspace_id from its OAuth token — the migration is invisible client-side.

If you need to force a machine into a different workspace explicitly, use:


cmdop connect workspace move <machine> --to <workspace>

Failure modes

Symptom	Likely cause	Fix
`sync: unauthorized`	OAuth token expired	`cmdop login`
`sync: workspace X not found`	Removed from workspace	Remove the local entry manually
Stale `LastSyncedAt`	Sync silently failed (network)	Re-run with `--debug`
Sync removed an API-key-only workspace	Should not happen; sync only updates OAuth-managed entries	File a ticket

Recommended cadence

After every cmdop login.
After membership changes (you joined or left a workspace).
Periodically in CI to ensure runners pick up new workspaces.

There is no harm in over-syncing — the call is idempotent and cheap.

Sync requires an OAuth token. API-key-only setups skip sync entirely; their workspace list is whatever you key set locally.