repos / zmx

commit

911f789

parent

538ed39

author

Eric Bower

date

2026-04-14 15:25:28 -0400 EDT

docs(readme): paste help msg

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

  1@@ -68,13 +68,15 @@ zig build -Doptimize=ReleaseSafe --prefix ~/.local
  2 > We recommend closing the terminal window to detach from the session but you can also press `ctrl+\` or run `zmx detach`.
  3 
  4 ```
  5-Usage: zmx <command> [args]
  6+zmx - session persistence for terminal processes
  7+
  8+Usage: zmx <command> [args...]
  9 
 10 Commands:
 11   [a]ttach <name> [command...]             Attach to session, creating if needed
 12   [r]un <name> [-d] [--fish] [command...]  Send command without attaching
 13   [wr]ite <name> <file_path>               Write stdin to file_path through the session
 14-  [d]etach                                 Detach all clients (ctrl+\ for current client)
 15+  [d]etach                                 Detach all clients (ctrl+\\ for current client)
 16   [l]ist [--short]                         List active sessions
 17   [k]ill <name>... [--force]               Kill session and all attached clients
 18   [hi]story <name> [--vt|--html]           Output session scrollback
 19@@ -83,22 +85,71 @@ Commands:
 20   [c]ompletions <shell>                    Shell completions (bash, zsh, fish)
 21   [v]ersion                                Show version
 22   [h]elp                                   Show this help
 23-```
 24-
 25-### examples
 26-
 27-```bash
 28-zmx attach dev              # start a shell session
 29-zmx a dev nvim .            # start nvim in a persistent session
 30-zmx attach build make -j8   # run a build, reattach to check progress
 31-zmx attach mux dvtm         # run a multiplexer inside zmx
 32-
 33-zmx run dev cat README.md   # run the command without attaching to the session
 34-zmx r dev cat CHANGELOG.md  # alias
 35-echo "ls -lah" | zmx r dev  # use stdin to run the command
 36 
 37-zmx r tests go test ./...   # run your tests in the background
 38-zmx wait tests              # waits for tests to complete
 39+Attach:
 40+  This will spawn a login $SHELL with a PTY.  You can provide a
 41+  command instead of creating a shell.
 42+
 43+  Examples:
 44+    zmx attach dev
 45+    zmx attach dev vim
 46+
 47+History:
 48+  This should generally be used with `tail` to print the last lines
 49+  of the session's scrollback history.
 50+
 51+  Examples:
 52+    zmx history <session> | tail -100
 53+
 54+Run:
 55+  Commands are passed as-is; do not wrap in quotes.
 56+  Commands run sequentially; do not send multiple in parallel.
 57+  Avoid interactive programs (pagers, editors, prompts) -- they hang.
 58+
 59+  `-d` will detach from the calling terminal. Use `wait` to track
 60+  its status.
 61+
 62+  `--fish` is required when the session runs fish shell.
 63+
 64+  If the command hangs, send Ctrl+C to recover:
 65+    zmx run <session> $'\\x03'
 66+
 67+  Examples:
 68+    zmx run dev ls
 69+    zmx run dev --fish ls src
 70+    zmx run dev zig build
 71+    zmx run dev grep -r TODO src
 72+    zmx run dev git -c core.pager=cat diff
 73+
 74+Write:
 75+  Writes stdin to file_path inside the session. Works over SSH.
 76+  file_path can be absolute or relative to the session shell's cwd.
 77+  Requires base64 and printf in the remote environment.
 78+  Large files are chunked automatically (~48KB per chunk).
 79+  File path must not contain single quotes.
 80+
 81+  Examples:
 82+    echo "hello" | zmx write dev /tmp/hello.txt
 83+    cat main.zig | zmx write dev src/main.zig
 84+
 85+Wait:
 86+  Used with a detached run task to track its status.  Multiple
 87+  sessions can be provided.
 88+
 89+  Examples:
 90+    zmx run -d dev sleep 10
 91+    zmx wait dev
 92+    zmx wait dev other
 93+
 94+Environment variables:
 95+  SHELL                Default shell for new sessions
 96+  ZMX_DIR              Socket directory (priority 1)
 97+  XDG_RUNTIME_DIR      Socket directory (priority 2)
 98+  TMPDIR               Socket directory (priority 3)
 99+  ZMX_SESSION          Session name (injected automatically)
100+  ZMX_SESSION_PREFIX   Prefix added to all session names
101+  ZMX_DIR_MODE         Sets mode for socket and log directories (octal, defaults to 0750)
102+  ZMX_LOG_MODE         Sets mode for log files (octal, defaults to 0640)
103 ```
104 
105 ## shell prompt