docs(readme): paste help msg

Commit `911f789`

Eric Bower · 2026-04-14 15:25:28 -0400 EDT

parent 538ed39

docs(readme): paste help msg

2 files changed, +69, -18

M CHANGELOG.md

M README.md

M CHANGELOG.md

+1, -1

......@@ -21,7 +21,7 @@ Use spec: https://common-changelog.org/
- `zmx run` accepts `--fish` flag to indicate the session's shell is fish
- `zmx kill` now supports multiple args and it will kill sessions that match a prefix
  - e.g. `zmx kill "d.*"` will kill all sessions that match that prefix
- *BREAKING* `kill` and `wait` now require "*" suffix for wildcard match sessions
- *BREAKING* `kill` and `wait` now require "\*" suffix for wildcard match sessions
  - e.g. `zmx kill "d.*"`, `zmx kill "*"`, `zmx wait "test*"`

### Fixed

M README.md

+68, -17

......@@ -68,13 +68,15 @@ zig build -Doptimize=ReleaseSafe --prefix ~/.local
> We recommend closing the terminal window to detach from the session but you can also press `ctrl+\` or run `zmx detach`.

```
Usage: zmx <command> [args]
zmx - session persistence for terminal processes

Usage: zmx <command> [args...]

Commands:
  [a]ttach <name> [command...]             Attach to session, creating if needed
  [r]un <name> [-d] [--fish] [command...]  Send command without attaching
  [wr]ite <name> <file_path>               Write stdin to file_path through the session
  [d]etach                                 Detach all clients (ctrl+\ for current client)
  [d]etach                                 Detach all clients (ctrl+\\ for current client)
  [l]ist [--short]                         List active sessions
  [k]ill <name>... [--force]               Kill session and all attached clients
  [hi]story <name> [--vt|--html]           Output session scrollback

......@@ -83,22 +85,71 @@ Commands:
  [c]ompletions <shell>                    Shell completions (bash, zsh, fish)
  [v]ersion                                Show version
  [h]elp                                   Show this help
```

### examples

```bash
zmx attach dev              # start a shell session
zmx a dev nvim .            # start nvim in a persistent session
zmx attach build make -j8   # run a build, reattach to check progress
zmx attach mux dvtm         # run a multiplexer inside zmx

zmx run dev cat README.md   # run the command without attaching to the session
zmx r dev cat CHANGELOG.md  # alias
echo "ls -lah" | zmx r dev  # use stdin to run the command

zmx r tests go test ./...   # run your tests in the background
zmx wait tests              # waits for tests to complete
Attach:
  This will spawn a login $SHELL with a PTY.  You can provide a
  command instead of creating a shell.

  Examples:
    zmx attach dev
    zmx attach dev vim

History:
  This should generally be used with `tail` to print the last lines
  of the session's scrollback history.

  Examples:
    zmx history <session> | tail -100

Run:
  Commands are passed as-is; do not wrap in quotes.
  Commands run sequentially; do not send multiple in parallel.
  Avoid interactive programs (pagers, editors, prompts) -- they hang.

  `-d` will detach from the calling terminal. Use `wait` to track
  its status.

  `--fish` is required when the session runs fish shell.

  If the command hangs, send Ctrl+C to recover:
    zmx run <session> $'\\x03'

  Examples:
    zmx run dev ls
    zmx run dev --fish ls src
    zmx run dev zig build
    zmx run dev grep -r TODO src
    zmx run dev git -c core.pager=cat diff

Write:
  Writes stdin to file_path inside the session. Works over SSH.
  file_path can be absolute or relative to the session shell's cwd.
  Requires base64 and printf in the remote environment.
  Large files are chunked automatically (~48KB per chunk).
  File path must not contain single quotes.

  Examples:
    echo "hello" | zmx write dev /tmp/hello.txt
    cat main.zig | zmx write dev src/main.zig

Wait:
  Used with a detached run task to track its status.  Multiple
  sessions can be provided.

  Examples:
    zmx run -d dev sleep 10
    zmx wait dev
    zmx wait dev other

Environment variables:
  SHELL                Default shell for new sessions
  ZMX_DIR              Socket directory (priority 1)
  XDG_RUNTIME_DIR      Socket directory (priority 2)
  TMPDIR               Socket directory (priority 3)
  ZMX_SESSION          Session name (injected automatically)
  ZMX_SESSION_PREFIX   Prefix added to all session names
  ZMX_DIR_MODE         Sets mode for socket and log directories (octal, defaults to 0750)
  ZMX_LOG_MODE         Sets mode for log files (octal, defaults to 0640)
```

## shell prompt

...	...		@@ -83,22 +85,71 @@ Commands:
83	85		[c]ompletions <shell> Shell completions (bash, zsh, fish)
84	86		[v]ersion Show version
85	87		[h]elp Show this help
86		-	```
87		-
88		-	### examples
89		-
90		-	```bash
91		-	zmx attach dev # start a shell session
92		-	zmx a dev nvim . # start nvim in a persistent session
93		-	zmx attach build make -j8 # run a build, reattach to check progress
94		-	zmx attach mux dvtm # run a multiplexer inside zmx
95		-
96		-	zmx run dev cat README.md # run the command without attaching to the session
97		-	zmx r dev cat CHANGELOG.md # alias
98		-	echo "ls -lah" \| zmx r dev # use stdin to run the command
99	88
100		-	zmx r tests go test ./... # run your tests in the background
101		-	zmx wait tests # waits for tests to complete
	89	+	Attach:
	90	+	This will spawn a login $SHELL with a PTY. You can provide a
	91	+	command instead of creating a shell.
	92	+
	93	+	Examples:
	94	+	zmx attach dev
	95	+	zmx attach dev vim
	96	+
	97	+	History:
	98	+	This should generally be used with `tail` to print the last lines
	99	+	of the session's scrollback history.
	100	+
	101	+	Examples:
	102	+	zmx history <session> \| tail -100
	103	+
	104	+	Run:
	105	+	Commands are passed as-is; do not wrap in quotes.
	106	+	Commands run sequentially; do not send multiple in parallel.
	107	+	Avoid interactive programs (pagers, editors, prompts) -- they hang.
	108	+
	109	+	`-d` will detach from the calling terminal. Use `wait` to track
	110	+	its status.
	111	+
	112	+	`--fish` is required when the session runs fish shell.
	113	+
	114	+	If the command hangs, send Ctrl+C to recover:
	115	+	zmx run <session> $'\\x03'
	116	+
	117	+	Examples:
	118	+	zmx run dev ls
	119	+	zmx run dev --fish ls src
	120	+	zmx run dev zig build
	121	+	zmx run dev grep -r TODO src
	122	+	zmx run dev git -c core.pager=cat diff
	123	+
	124	+	Write:
	125	+	Writes stdin to file_path inside the session. Works over SSH.
	126	+	file_path can be absolute or relative to the session shell's cwd.
	127	+	Requires base64 and printf in the remote environment.
	128	+	Large files are chunked automatically (~48KB per chunk).
	129	+	File path must not contain single quotes.
	130	+
	131	+	Examples:
	132	+	echo "hello" \| zmx write dev /tmp/hello.txt
	133	+	cat main.zig \| zmx write dev src/main.zig
	134	+
	135	+	Wait:
	136	+	Used with a detached run task to track its status. Multiple
	137	+	sessions can be provided.
	138	+
	139	+	Examples:
	140	+	zmx run -d dev sleep 10
	141	+	zmx wait dev
	142	+	zmx wait dev other
	143	+
	144	+	Environment variables:
	145	+	SHELL Default shell for new sessions
	146	+	ZMX_DIR Socket directory (priority 1)
	147	+	XDG_RUNTIME_DIR Socket directory (priority 2)
	148	+	TMPDIR Socket directory (priority 3)
	149	+	ZMX_SESSION Session name (injected automatically)
	150	+	ZMX_SESSION_PREFIX Prefix added to all session names
	151	+	ZMX_DIR_MODE Sets mode for socket and log directories (octal, defaults to 0750)
	152	+	ZMX_LOG_MODE Sets mode for log files (octal, defaults to 0640)
102	153		```
103	154
104	155		## shell prompt

...	...		@@ -21,7 +21,7 @@ Use spec: https://common-changelog.org/
21	21		- `zmx run` accepts `--fish` flag to indicate the session's shell is fish
22	22		- `zmx kill` now supports multiple args and it will kill sessions that match a prefix
23	23		- e.g. `zmx kill "d.*"` will kill all sessions that match that prefix
24		-	- BREAKING `kill` and `wait` now require "*" suffix for wildcard match sessions
	24	+	- BREAKING `kill` and `wait` now require "\*" suffix for wildcard match sessions
25	25		- e.g. `zmx kill "d."`, `zmx kill ""`, `zmx wait "test*"`
26	26
27	27		### Fixed

...	...		@@ -68,13 +68,15 @@ zig build -Doptimize=ReleaseSafe --prefix ~/.local
68	68		> We recommend closing the terminal window to detach from the session but you can also press `ctrl+\` or run `zmx detach`.
69	69
70	70		```
71		-	Usage: zmx <command> [args]
	71	+	zmx - session persistence for terminal processes
	72	+
	73	+	Usage: zmx <command> [args...]
72	74
73	75		Commands:
74	76		[a]ttach <name> [command...] Attach to session, creating if needed
75	77		[r]un <name> [-d] [--fish] [command...] Send command without attaching
76	78		[wr]ite <name> <file_path> Write stdin to file_path through the session
77		-	[d]etach Detach all clients (ctrl+\ for current client)
	79	+	[d]etach Detach all clients (ctrl+\\ for current client)
78	80		[l]ist [--short] List active sessions
79	81		[k]ill <name>... [--force] Kill session and all attached clients
80	82		[hi]story <name> [--vt\|--html] Output session scrollback

Commit 911f789

Commit `911f789`