Skip to Content

cmdop connect

cmdop connect is the CLI surface for reaching machines registered in your CMDOP workspace. It replaces what other tools call “SSH”: no keys, no port forwarding, no IPs — just an outbound-only relay identified by hostname or UUID.

This is the verb reference. For the story of how connect fits with the desktop machine inspector and server-to-server agent comms, see the Connect overview.

The subcommand tree

cmdop connect [hostname]              # interactive picker / direct attach
cmdop connect exec <host> -- <cmd...> # one-shot command, structured output
cmdop connect share <host>            # mint a time-limited access link
cmdop connect key {set|get|clear}     # workspace API key management
cmdop connect workspace {list|use|remove|sync}  # multi-workspace
cmdop connect password                # per-machine agent password

cmdop connect (no args) drops you into the picker — a fuzzy-search TUI over the workspace’s machines, sorted by recent usage. With a hostname argument it skips the picker and attaches directly.

Global flags

These work on every subcommand:

FlagPurpose
--api-key, -k <key>Override the resolved API key for this call.
--server, -s <addr>Override the gRPC server (for self-hosted relays).
--workspace <name>Use the named workspace instead of the active one.
--jsonEmit structured output (implies --no-interactive).
--no-interactive, -qNever prompt; fail fast if data is missing.

--list and --list --online are top-level shortcuts that print the machine inventory and exit.

Interactive attach

cmdop connect            # picker → confirm → attach
cmdop connect vps-audi   # direct attach (skip picker)

The picker honors Ctrl-C to cancel. After picking, a confirm step shows machine name, hostname, online status, and last heartbeat before opening the PTY. Inside the session:

  • Ctrl-C is forwarded to the remote shell as SIGINT.
  • Ctrl-D disconnects locally — it is not forwarded.
  • Window resizes (SIGWINCH) propagate so top/htop/editors redraw correctly.
  • Disconnects bubble up as ErrUserDisconnected, returning you to the picker if you ran cmdop connect with no args.

Hostname accepts exact hostname, display name, unique prefix, or full UUID. Ambiguous matches print a candidate list; UUID-shaped arguments never fall through to fuzzy matching. See Machines & identity.

One-shot exec

cmdop connect exec vps-audi -- uname -a
cmdop connect exec mac-studio --json -- df -h
cmdop connect exec prod-api-1 --timeout 60 -- systemctl status nginx

exec runs a single command, streams stdout/stderr back, and exits with the remote’s status code. With --json it prints a structured envelope ({stdout, stderr, exit_code, duration_ms}) — useful for scripts and the agent tool surface.

The default timeout is 30s. Anything longer than your network’s keepalive can drop without warning unless you bump --timeout.

cmdop connect share vps-audi               # default 24h TTL
cmdop connect share vps-audi --ttl 4h
cmdop connect share vps-audi --ttl 0       # never expires

A share link mints a time-limited access token bound to one machine. Hand it to a collaborator and they can attach without belonging to your workspace. TTL is hours-only (sub-hour values round up). See Share links for the receiver’s perspective.

Workspace management

cmdop connect workspace is multi-workspace switching from the CLI:

cmdop connect workspace list           # show all, mark active
cmdop connect workspace use prod       # set active
cmdop connect workspace remove staging # delete locally
cmdop connect workspace sync           # OAuth → fetch from server

Workspaces live in ~/.cmdop/ssh_workspaces.json (mode 0600). Each holds a name, an optional API key, and an optional server override. sync requires cmdop login first — it pulls the authoritative list from the relay and upserts, preserving your local API keys. Full background: Workspaces.

API key management

cmdop connect key set <KEY>   # store an API key in the active workspace
cmdop connect key get          # print the masked key (first/last 4)
cmdop connect key clear        # remove it

The legacy form cmdop connect set-key <KEY> is still accepted but prints a deprecation notice; switch to key set.

Credential resolution

When any cmdop connect subcommand needs a credential it walks this chain (first hit wins):

  1. --api-key flag.
  2. CMDOP_API_KEY environment variable.
  3. The named workspace from --workspace.
  4. The active workspace’s stored key.
  5. A legacy cfg.Chat.GrpcAPIKey (one-shot migration).
  6. The OAuth access token from cmdop login — the universal fallback for humans.

Long-form: Credential resolver.

API keys are workspace-scoped. OAuth tokens are user-scoped and cross workspaces. If a command fails with unauthorized, the error message names the source so you can fix the right one.

Per-machine passwords

Some machines are registered with an attach password (bcrypt-hashed server-side). The first time you attach you’ll see a streaming AuthChallenge; CMDOP prompts for the password and caches a 24-hour session token in memory. Subsequent unary RPCs against the same session reuse the token automatically.

cmdop connect password set vps-audi   # remember it locally
cmdop connect password clear vps-audi
cmdop connect password list           # which machines have one stored

Background: Auth & passwords.

Scripting

--json plus --no-interactive is the safe combination for CI and agents. With both set, cmdop connect never prompts, never opens a picker, and emits structured output:

cmdop connect exec vps-audi --json --no-interactive -- date
# {"stdout":"...","stderr":"","exit_code":0,"duration_ms":42}

Exit codes follow conventions: 0 success, 1 generic error, 2 auth failure, 3 machine offline, 4 ambiguous hostname.

Last updated on
What is CMDOP