Sessions

A session is the durable backing of a remote terminal: a PTY plus a ringbuffer plus an idle TTL. Sessions outlive the client. Detach with Ctrl+D and the session keeps running on the target machine; reattach from anywhere.

What a session is

When you cmdop terminal vps-audi (or cmdop connect vps-audi), the daemon spawns or reuses a session on vps-audi. The session owns the PTY, the running processes, and a scrollback ringbuffer. Closing the client doesn’t kill the session — it survives until you destroy it or the idle TTL expires.

Create / list


cmdop session create vps-audi --name deploy
cmdop session list                       # all your sessions
cmdop session list --host vps-audi
cmdop session list --json

A bare cmdop terminal vps-audi also creates a session implicitly — cmdop session create is for when you want to script the creation without attaching immediately.

Attach / detach


cmdop session attach 0193e2c1-7a8f-7b33-8c01
cmdop session attach deploy              # by name (if unique on this host)
cmdop session detach 0193e2c1-7a8f-7b33-8c01

Multiple clients can attach to the same session — all see each other’s keystrokes (pair-debugging).

To force-detach others when attaching:


cmdop session attach --takeover 0193e2c1-7a8f-7b33-8c01

Save / restore


cmdop session save 0193e2c1-... --to ./session-snapshot.json
cmdop session restore --from ./session-snapshot.json

save snapshots the ringbuffer (last N lines) and PTY metadata. restore is for migrating session metadata between machines — rare, mostly for internal tooling.

Destroy


cmdop session destroy 0193e2c1-7a8f-7b33-8c01
cmdop session destroy --idle 24h         # nuke all idle for >24h

Destroy kills the PTY and removes the ringbuffer. Sessions also auto-expire after the configured idle TTL (default 7 days).

Triggers vs sessions

Both live under cmd/cmdop/cmds/session/ because both are stateful CLI concepts:

	Sessions	Triggers
Trigger	Operator attach	Cron schedule
Lifetime	Idle TTL	Until disabled
Output	Live PTY	Logs + Board entry
Use for	Interactive work	Scheduled automation

See ./trigger for the scheduled-task surface.

Inspecting session ringbuffers


cmdop session show 0193e2c1-...        # metadata
cmdop session show 0193e2c1-... --tail 200  # last 200 lines of scrollback

Useful for “what was on screen 4 hours ago?” without reattaching.

Troubleshooting

“Session shows attached but no input echoes” — another client may have it; cmdop session attach --takeover <id> to force-detach others.
“Session disappeared” — check the idle TTL in ~/.cmdop/config.yaml; default is 7 days.
“Cannot create session: target offline” — confirm the target with cmdop machines; remote daemon must be running.