Fleet sync
Logging in with cmdop login pulls the authoritative fleet list from the server and updates ssh_workspaces.json. There is no separate cmdop connect workspace sync verb — OAuth login refreshes the list. Re-authenticate 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 fleet populated locally.
- You were added to a new fleet by a teammate.
- A fleet was renamed in the cabinet.
- You suspect your local fleet list is stale.
- You switched modes (
prod↔dev) and want the new mode’s fleets.
How sync works
cmdop loginOn login the CLI:
- Authenticates with OAuth (fleet enumeration requires OAuth — API keys do not have permission to enumerate fleets).
- Compares the response to
ssh_workspaces.json. - Adds new fleets, updates
RemoteIDandLastSyncedAton existing ones, marks fleets you have left as inactive (does not delete the API key — you may still want it). - Persists atomically.
API-key fleets 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 fleet pointer — login does not change which fleet 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 fleet set. Switch modes with:
cmdop --dev login # authenticates against the dev serverThe 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
Login does not move machines between fleets. If a machine was migrated server-side (e.g. you switched fleets 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.
To move a machine into a different fleet explicitly, change its fleet in the web cabinet — the move is recorded in the activity log.
Failure modes
| Symptom | Likely cause | Fix |
|---|---|---|
sync: unauthorized | OAuth token expired | cmdop login |
sync: fleet X not found | Removed from fleet | Remove the local entry manually |
Stale LastSyncedAt | Sync silently failed (network) | Re-run with --debug |
| Login removed an API-key-only fleet | Should not happen; login only updates OAuth-managed entries | File a ticket |
Recommended cadence
- After every
cmdop login. - After membership changes (you joined or left a fleet).
- Periodically in CI to ensure runners pick up new fleets.
There is no harm in over-syncing — login is idempotent.
Fleet enumeration requires an OAuth token. API-key-only setups skip sync entirely; their fleet list is whatever key you supply via --api-key or CMDOP_API_KEY.
Cmdop