docs: help cmd - zmx@2e2b64b

Commit `2e2b64b`

Eric Bower · 2026-06-12 19:57:10 -0400 EDT

parent 94738e5

docs: help cmd

2 files changed, +6, -96

M README.md

M src/main.zig

M README.md

+2, -96

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

```
zmx - session persistence for terminal processes
Run `zmx help` for more information on usage, with examples.

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

Commands:

......@@ -91,100 +91,6 @@ Commands:
  [c]ompletions <shell>                    Shell completions (bash, zsh, fish)
  [v]ersion                                Show version
  [h]elp                                   Show this help

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.

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

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

  If the command hangs, print the history to see the error:
    zmx history <session> | tail -100

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

  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

Send:
  Sends raw text to the session's PTY input (fire-and-forget).
  Unlike `run`, no completion marker is appended and no exit code
  is tracked.  Useful for TUI applications, interactive prompts,
  or any program that reads stdin directly.

  Text is sent byte-for-byte with no automatic carriage return.
  Append \r yourself when you want the shell to execute a command.

  Text can also be piped via stdin:
    printf 'ls -la\r' | zmx send dev

  Examples:
    printf 'echo hello\r' | zmx send dev
    zmx send dev $(printf '\x03')
    zmx send dev /compact

Print:
  Injects text directly into the session display and scrollback.
  Never touches the PTY input -- the shell sees nothing.
  Caller is responsible for newlines (\\r\\n).

  Examples:
    printf '\\r\\nhello\\r\\n' | zmx print dev
    zmx print dev "$(printf '\\r\\nalert\\r\\n')"

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

M src/main.zig

+4, -0

......@@ -1279,6 +1279,7 @@ fn help() !void {
        \\    zmx history <session> | tail -100
        \\
        \\Run:
        \\  Commands run inside a PTY using bash
        \\  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.

......@@ -1298,6 +1299,9 @@ fn help() !void {
        \\    zmx run dev grep -r TODO src
        \\    zmx run dev git -c core.pager=cat diff
        \\
        \\    zmx run dev -d sleep 10
        \\    zmx wait dev
        \\
        \\Send:
        \\  Sends raw text to the session's PTY input (fire-and-forget).
        \\  Unlike `run`, no completion marker is appended and no exit code

...	...		@@ -91,100 +91,6 @@ Commands:
91	91		[c]ompletions <shell> Shell completions (bash, zsh, fish)
92	92		[v]ersion Show version
93	93		[h]elp Show this help
94		-
95		-	Attach:
96		-	This will spawn a login $SHELL with a PTY. You can provide a
97		-	command instead of creating a shell.
98		-
99		-	Examples:
100		-	zmx attach dev
101		-	zmx attach dev vim
102		-
103		-	History:
104		-	This should generally be used with `tail` to print the last lines
105		-	of the session's scrollback history.
106		-
107		-	Examples:
108		-	zmx history <session> \| tail -100
109		-
110		-	Run:
111		-	Commands are passed as-is: do not wrap in quotes.
112		-	Commands run sequentially: do not send multiple in parallel.
113		-	Avoid interactive programs (pagers, editors, prompts): they hang.
114		-
115		-	`--fish` is required when the session runs fish shell.
116		-
117		-	If the command hangs, send Ctrl+C to recover:
118		-	zmx run <session> $(printf '\x03')
119		-
120		-	If the command hangs, print the history to see the error:
121		-	zmx history <session> \| tail -100
122		-
123		-	`-d` will detach from the calling terminal. Use `wait` to track
124		-	its status.
125		-
126		-	Examples:
127		-	zmx run dev ls
128		-	zmx run dev --fish ls src
129		-	zmx run dev zig build
130		-	zmx run dev grep -r TODO src
131		-	zmx run dev git -c core.pager=cat diff
132		-
133		-	Send:
134		-	Sends raw text to the session's PTY input (fire-and-forget).
135		-	Unlike `run`, no completion marker is appended and no exit code
136		-	is tracked. Useful for TUI applications, interactive prompts,
137		-	or any program that reads stdin directly.
138		-
139		-	Text is sent byte-for-byte with no automatic carriage return.
140		-	Append \r yourself when you want the shell to execute a command.
141		-
142		-	Text can also be piped via stdin:
143		-	printf 'ls -la\r' \| zmx send dev
144		-
145		-	Examples:
146		-	printf 'echo hello\r' \| zmx send dev
147		-	zmx send dev $(printf '\x03')
148		-	zmx send dev /compact
149		-
150		-	Print:
151		-	Injects text directly into the session display and scrollback.
152		-	Never touches the PTY input -- the shell sees nothing.
153		-	Caller is responsible for newlines (\\r\\n).
154		-
155		-	Examples:
156		-	printf '\\r\\nhello\\r\\n' \| zmx print dev
157		-	zmx print dev "$(printf '\\r\\nalert\\r\\n')"
158		-
159		-	Write:
160		-	Writes stdin to file_path inside the session. Works over SSH.
161		-	file_path can be absolute or relative to the session shell's cwd.
162		-	Requires base64 and printf in the remote environment.
163		-	Large files are chunked automatically (~48KB per chunk).
164		-	File path must not contain single quotes.
165		-
166		-	Examples:
167		-	echo "hello" \| zmx write dev /tmp/hello.txt
168		-	cat main.zig \| zmx write dev src/main.zig
169		-
170		-	Wait:
171		-	Used with a detached run task to track its status. Multiple
172		-	sessions can be provided.
173		-
174		-	Examples:
175		-	zmx run -d dev sleep 10
176		-	zmx wait dev
177		-	zmx wait dev other
178		-
179		-	Environment variables:
180		-	SHELL Default shell for new sessions
181		-	ZMX_DIR Socket directory (priority 1)
182		-	XDG_RUNTIME_DIR Socket directory (priority 2)
183		-	TMPDIR Socket directory (priority 3)
184		-	ZMX_SESSION Session name (injected automatically)
185		-	ZMX_SESSION_PREFIX Prefix added to all session names
186		-	ZMX_DIR_MODE Sets mode for socket and log directories (octal, defaults to 0750)
187		-	ZMX_LOG_MODE Sets mode for log files (octal, defaults to 0640)
188	94		```
189	95
190	96		## shell prompt

...	...		@@ -71,9 +71,9 @@ zig build -Doptimize=ReleaseSafe --prefix ~/.local
71	71		> [!IMPORTANT]
72	72		> We recommend closing the terminal window to detach from the session but you can also press `ctrl+\` or run `zmx detach`.
73	73
74		-	```
75		-	zmx - session persistence for terminal processes
	74	+	Run `zmx help` for more information on usage, with examples.
76	75
	76	+	```
77	77		Usage: zmx <command> [args...]
78	78
79	79		Commands:

...	...		@@ -1279,6 +1279,7 @@ fn help() !void {
1279	1279		\\ zmx history <session> \| tail -100
1280	1280		\\
1281	1281		\\Run:
	1282	+	\\ Commands run inside a PTY using bash
1282	1283		\\ Commands are passed as-is: do not wrap in quotes.
1283	1284		\\ Commands run sequentially: do not send multiple in parallel.
1284	1285		\\ Avoid interactive programs (pagers, editors, prompts): they hang.

...	...		@@ -1298,6 +1299,9 @@ fn help() !void {
1298	1299		\\ zmx run dev grep -r TODO src
1299	1300		\\ zmx run dev git -c core.pager=cat diff
1300	1301		\\
	1302	+	\\ zmx run dev -d sleep 10
	1303	+	\\ zmx wait dev
	1304	+	\\
1301	1305		\\Send:
1302	1306		\\ Sends raw text to the session's PTY input (fire-and-forget).
1303	1307		\\ Unlike `run`, no completion marker is appended and no exit code

Commit 2e2b64b

Commit `2e2b64b`