cmdop connect

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

The subcommand tree

cmdop connect [hostname]              # interactive picker / direct attach
cmdop connect exec <host> -- <cmd...> # one-shot command, structured output
cmdop connect password {set|clear|list|status}  # 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:

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, fleet name, 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.

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.

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    # store password for this machine
cmdop connect password status # check if a password is set
cmdop connect password clear  # remove it
cmdop connect password list   # list machines that have a password stored

Background: Auth & passwords.

Fleet selection

A fleet (the --workspace flag still carries the legacy name) is the credential boundary around a set of machines. To target a specific fleet without changing your active one, use the --workspace flag — it is a flag, not a subcommand:

cmdop connect --workspace acme-prod vps-audi
cmdop connect --workspace acme-staging exec prod-1 -- uptime
cmdop connect --list --workspace acme-prod

See Fleets & workspaces for credential precedence and local storage details.

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 fleet from --workspace.
4. The active fleet’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.

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.

Machine inventory

cmdop connect --list              # all registered machines in the active fleet
cmdop connect --list --online     # only currently connected machines
cmdop connect --list --json       # machine list as JSON

Related

• Connect overview — the full story (CLI + Desktop + agent-to-agent).
• Server-to-server — ask_machine and ask_machines between machines.
• Fleets & workspaces — fleet selection and credential management.