docs: formatting cli help

Commit `2d23c0d`

Eric Bower · 2026-10-03 13:27:58 -0400 EDT

parent 20c0d5e

docs: formatting cli help

3 files changed, +38, -48

M CHANGELOG.md

M README.md

M src/main.zig

M CHANGELOG.md

+1, -0

......@@ -7,6 +7,7 @@ Use spec: https://common-changelog.org/
### Added

- Completions for [`yash`](https://magicant.github.io/yash/)
- History command now accepts --screen (print only active screen) and --scrollback (num of rows to print)

### Fixed

M README.md

+19, -30

......@@ -101,36 +101,25 @@ Run `zmx help` for more information on usage, with examples.
Usage: zmx <command> [args...]

Commands:
  [a]ttach <name> [command...]             Attach to session, creating if needed
  [r]un <name> [-d] [command...]           Send command without attaching
  [s]end <name> <text...>                  Send raw input to session PTY
  [p]rint <name> <text...>                 Inject text into session display
  [wr]ite <name> <file_path>               Write stdin to file_path through the session
  [d]etach                                 Detach all clients (ctrl+\\ for current client)
  [l]ist|ls [--short]                      List active sessions
  [g]et <name>                             Get session labels
  set <name> k=v ...                       Set session labels
  [cl]ear <name>                           Clear all session labels
  print-env [-s] <name> [key]              Print tracked environment variables
  [k]ill <name>... [--force]               Kill session and all attached clients
  [hi]story <name> [--vt|--html]           Output session scrollback
  [w]ait <name>...                         Wait for session tasks to complete
  [t]ail <name>...                         Follow session output
  [c]ompletions <shell>                    Shell completions (bash, zsh, fish, nu, yash)
  [v]ersion                                Show version and metadata (socket dir, log dir)
  [h]elp                                   Show this help
```

### screen and scrollback capture

`zmx history --screen <name>` prints only the active screen, and
`zmx history --scrollback N <name>` adds up to `N` rows of scrollback above it.
Both work with `--vt` and `--html`. The daemon selects the rows before
formatting them, so a tool that polls a session's current state no longer
receives and discards the whole history. Alternate screens have no scrollback,
so they always return just the screen. Sessions whose daemon predates this
feature keep serving plain `history`; the scoped flags report that the daemon
is too old.
  [a]ttach <name> [command...]                             Attach to session, creating if needed
  [r]un <name> [-d] [command...]                           Send command without attaching
  [s]end <name> <text...>                                  Send raw input to session PTY
  [p]rint <name> <text...>                                 Inject text into session display
  [wr]ite <name> <file_path>                               Write stdin to file_path through the session
  [d]etach                                                 Detach all clients (ctrl+\\ for current client)
  [l]ist|ls [--short]                                      List active sessions
  [g]et <name>                                             Get session labels
  set <name> k=v ...                                       Set session labels
  [cl]ear <name>                                           Clear all session labels
  print-env [-s] <name> [key]                              Print tracked environment variables
  [k]ill <name>... [--force]                               Kill session and all attached clients
  [hi]story <name> [--vt|--html] [--screen|scrollback]     Output session scrollback
  [w]ait <name>...                                         Wait for session tasks to complete
  [t]ail <name>...                                         Follow session output
  [c]ompletions <shell>                                    Shell completions (bash, zsh, fish, nu, yash)
  [v]ersion                                                Show version and metadata (socket dir, log dir)
  [h]elp                                                   Show this help
```

## nested sessions

M src/main.zig

+18, -18

......@@ -517,24 +517,24 @@ fn help(io: std.Io) !void {
        \\Usage: zmx <command> [args...]
        \\
        \\Commands:
        \\  [a]ttach [--labels kv] <name> [command...]  Attach to session, creating if needed
        \\  [r]un <name> [-d] [command...]              Send command without attaching
        \\  [s]end <name> <text...>                     Send raw input to session PTY
        \\  [p]rint <name> <text...>                    Inject text into session display
        \\  [wr]ite <name> <file_path>                  Write stdin to file_path through the session
        \\  [d]etach                                    Detach all clients (ctrl+\\ for current client)
        \\  [l]ist|ls [--short]                         List active sessions
        \\  [g]et <name>                                Get session labels
        \\  set <name> k=v ...                          Set session labels (k= to remove)
        \\  [cl]ear <name>                              Clear all session labels
        \\  print-env [-s] <name> [key]                 Print tracked environment variables
        \\  [k]ill <name>... [--force]                  Kill session and all attached clients
        \\  [hi]story <name> [--vt|--html]              Output session scrollback
        \\  [w]ait <name>...                            Wait for session tasks to complete
        \\  [t]ail <name>...                            Follow session output
        \\  [c]ompletions <shell>                       Shell completions (bash, zsh, fish, nu, yash)
        \\  [v]ersion                                   Show version and metadata (socket dir, log dir)
        \\  [h]elp                                      Show this help
        \\  [a]ttach [--labels kv] <name> [command...]                 Attach to session, creating if needed
        \\  [r]un <name> [-d] [command...]                             Send command without attaching
        \\  [s]end <name> <text...>                                    Send raw input to session PTY
        \\  [p]rint <name> <text...>                                   Inject text into session display
        \\  [wr]ite <name> <file_path>                                 Write stdin to file_path through the session
        \\  [d]etach                                                   Detach all clients (ctrl+\\ for current client)
        \\  [l]ist|ls [--short]                                        List active sessions
        \\  [g]et <name>                                               Get session labels
        \\  set <name> k=v ...                                         Set session labels (k= to remove)
        \\  [cl]ear <name>                                             Clear all session labels
        \\  print-env [-s] <name> [key]                                Print tracked environment variables
        \\  [k]ill <name>... [--force]                                 Kill session and all attached clients
        \\  [hi]story <name> [--vt|--html] [--screen|--scrollback]     Output session scrollback
        \\  [w]ait <name>...                                           Wait for session tasks to complete
        \\  [t]ail <name>...                                           Follow session output
        \\  [c]ompletions <shell>                                      Shell completions (bash, zsh, fish, nu, yash)
        \\  [v]ersion                                                  Show version and metadata (socket dir, log dir)
        \\  [h]elp                                                     Show this help
        \\
        \\Attach:
        \\  This will spawn a login $SHELL with a PTY.  You can provide a

...	...		@@ -101,36 +101,25 @@ Run `zmx help` for more information on usage, with examples.
101	101		Usage: zmx <command> [args...]
102	102
103	103		Commands:
104		-	[a]ttach <name> [command...] Attach to session, creating if needed
105		-	[r]un <name> [-d] [command...] Send command without attaching
106		-	[s]end <name> <text...> Send raw input to session PTY
107		-	[p]rint <name> <text...> Inject text into session display
108		-	[wr]ite <name> <file_path> Write stdin to file_path through the session
109		-	[d]etach Detach all clients (ctrl+\\ for current client)
110		-	[l]ist\|ls [--short] List active sessions
111		-	[g]et <name> Get session labels
112		-	set <name> k=v ... Set session labels
113		-	[cl]ear <name> Clear all session labels
114		-	print-env [-s] <name> [key] Print tracked environment variables
115		-	[k]ill <name>... [--force] Kill session and all attached clients
116		-	[hi]story <name> [--vt\|--html] Output session scrollback
117		-	[w]ait <name>... Wait for session tasks to complete
118		-	[t]ail <name>... Follow session output
119		-	[c]ompletions <shell> Shell completions (bash, zsh, fish, nu, yash)
120		-	[v]ersion Show version and metadata (socket dir, log dir)
121		-	[h]elp Show this help
122		-	```
123		-
124		-	### screen and scrollback capture
125		-
126		-	`zmx history --screen <name>` prints only the active screen, and
127		-	`zmx history --scrollback N <name>` adds up to `N` rows of scrollback above it.
128		-	Both work with `--vt` and `--html`. The daemon selects the rows before
129		-	formatting them, so a tool that polls a session's current state no longer
130		-	receives and discards the whole history. Alternate screens have no scrollback,
131		-	so they always return just the screen. Sessions whose daemon predates this
132		-	feature keep serving plain `history`; the scoped flags report that the daemon
133		-	is too old.
	104	+	[a]ttach <name> [command...] Attach to session, creating if needed
	105	+	[r]un <name> [-d] [command...] Send command without attaching
	106	+	[s]end <name> <text...> Send raw input to session PTY
	107	+	[p]rint <name> <text...> Inject text into session display
	108	+	[wr]ite <name> <file_path> Write stdin to file_path through the session
	109	+	[d]etach Detach all clients (ctrl+\\ for current client)
	110	+	[l]ist\|ls [--short] List active sessions
	111	+	[g]et <name> Get session labels
	112	+	set <name> k=v ... Set session labels
	113	+	[cl]ear <name> Clear all session labels
	114	+	print-env [-s] <name> [key] Print tracked environment variables
	115	+	[k]ill <name>... [--force] Kill session and all attached clients
	116	+	[hi]story <name> [--vt\|--html] [--screen\|scrollback] Output session scrollback
	117	+	[w]ait <name>... Wait for session tasks to complete
	118	+	[t]ail <name>... Follow session output
	119	+	[c]ompletions <shell> Shell completions (bash, zsh, fish, nu, yash)
	120	+	[v]ersion Show version and metadata (socket dir, log dir)
	121	+	[h]elp Show this help
	122	+	```
134	123
135	124		## nested sessions
136	125

...	...		@@ -7,6 +7,7 @@ Use spec: https://common-changelog.org/
7	7		### Added
8	8
9	9		- Completions for [`yash`](https://magicant.github.io/yash/)
	10	+	- History command now accepts --screen (print only active screen) and --scrollback (num of rows to print)
10	11
11	12		### Fixed
12	13

...	...		@@ -517,24 +517,24 @@ fn help(io: std.Io) !void {
517	517		\\Usage: zmx <command> [args...]
518	518		\\
519	519		\\Commands:
520		-	\\ [a]ttach [--labels kv] <name> [command...] Attach to session, creating if needed
521		-	\\ [r]un <name> [-d] [command...] Send command without attaching
522		-	\\ [s]end <name> <text...> Send raw input to session PTY
523		-	\\ [p]rint <name> <text...> Inject text into session display
524		-	\\ [wr]ite <name> <file_path> Write stdin to file_path through the session
525		-	\\ [d]etach Detach all clients (ctrl+\\ for current client)
526		-	\\ [l]ist\|ls [--short] List active sessions
527		-	\\ [g]et <name> Get session labels
528		-	\\ set <name> k=v ... Set session labels (k= to remove)
529		-	\\ [cl]ear <name> Clear all session labels
530		-	\\ print-env [-s] <name> [key] Print tracked environment variables
531		-	\\ [k]ill <name>... [--force] Kill session and all attached clients
532		-	\\ [hi]story <name> [--vt\|--html] Output session scrollback
533		-	\\ [w]ait <name>... Wait for session tasks to complete
534		-	\\ [t]ail <name>... Follow session output
535		-	\\ [c]ompletions <shell> Shell completions (bash, zsh, fish, nu, yash)
536		-	\\ [v]ersion Show version and metadata (socket dir, log dir)
537		-	\\ [h]elp Show this help
	520	+	\\ [a]ttach [--labels kv] <name> [command...] Attach to session, creating if needed
	521	+	\\ [r]un <name> [-d] [command...] Send command without attaching
	522	+	\\ [s]end <name> <text...> Send raw input to session PTY
	523	+	\\ [p]rint <name> <text...> Inject text into session display
	524	+	\\ [wr]ite <name> <file_path> Write stdin to file_path through the session
	525	+	\\ [d]etach Detach all clients (ctrl+\\ for current client)
	526	+	\\ [l]ist\|ls [--short] List active sessions
	527	+	\\ [g]et <name> Get session labels
	528	+	\\ set <name> k=v ... Set session labels (k= to remove)
	529	+	\\ [cl]ear <name> Clear all session labels
	530	+	\\ print-env [-s] <name> [key] Print tracked environment variables
	531	+	\\ [k]ill <name>... [--force] Kill session and all attached clients
	532	+	\\ [hi]story <name> [--vt\|--html] [--screen\|--scrollback] Output session scrollback
	533	+	\\ [w]ait <name>... Wait for session tasks to complete
	534	+	\\ [t]ail <name>... Follow session output
	535	+	\\ [c]ompletions <shell> Shell completions (bash, zsh, fish, nu, yash)
	536	+	\\ [v]ersion Show version and metadata (socket dir, log dir)
	537	+	\\ [h]elp Show this help
538	538		\\
539	539		\\Attach:
540	540		\\ This will spawn a login $SHELL with a PTY. You can provide a

Commit 2d23c0d

Commit `2d23c0d`