summaryrefslogtreecommitdiff
path: root/docs/typ/command-line.txt
blob: 5045a9831faf33d9c40375b7af9cef10050635fd (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
pardes: an editor, a terminal multiplexer, and the file tree that scripts both.

Usage:
  pardes [flags] [FILE[:LINE] | DIR | -]   open, start a session, or page stdin
  pardes COMMAND [ARGS] [-s NAME]          a file named like a command: pardes ./ps

Open:
  FILE[:LINE]            open it; in a pane, in that pane's session
  -w, --wait FILE        open it, return when its pane closes (EDITOR='pardes -w')
  -                      stdin into a +Pager, its colours kept
  DIR                    start in it

Sessions:
  ps                     the daemon's sessions, their clients and shells
  attach [NAME]          show a detached session here (HOST:NAME: over ssh)
  kill NAME              end a session and its shells (--all: every one)
  new [flags] [FILE]     start one: --detach=NAME --9p=NAME -n 3 (help new)

Words:
  do WORD [ARG]          run a builtin at this pane, or the session's: do Newcol
  words [GROUP]          the builtins by group, or one group's: words column

Files:
  fs VERB [PATH]         ls read write ask follow stat help complete, on the session's tree

Self:
  help [CMD|WORD|PATH]   this, a command, a builtin, or a file of the tree
  completion SHELL       bash, fish or zsh
  skill                  the guide an agent reads
  version                this build, its session wire and its 9P

Flags:
  -s, --session NAME     the session to act on ($PARDES_9P, else the only one)
  -p N                   the pane, for do ($PARDES_PANE)

The old spellings --ps, --attach[=NAME], --kill=NAME, --kill-all, -h and
--version still work, for a release.

== pardes help ps

What the per-user daemon keeps: each session with its name, pid, kind
(tty or gui) and whether one is attached; under it its clients and its
shells; then the shells no session holds, which Adopt takes. /sessions
is the same list, read from inside a session.

Usage:
  pardes ps

Examples:
  pardes ps                             every session, client and shell

See also: attach, kill, /sessions

== pardes help attach

Show a detached session here: in this terminal for pardes, a window
for pardes-gui. Bare, the one detached session (with none, the one
session). One attached already, or of the other kind, is joined as a
client. HOST:NAME is a client of session NAME on another machine,
over `ssh -L` to its pardes-replica.sock ($PARDES_SSH: the ssh
command, default ssh; $PARDES_REMOTE_RUNTIME: its runtime directory,
if not this one's path); SOCK:NAME goes through a socket forwarded
already (a path, with a '/'). Returns when the session detaches or
ends.

Usage:
  pardes attach [NAME]

Examples:
  pardes attach                         the one detached session
  pardes attach notes                   the one started with --detach=notes
  pardes attach box:notes               on host box, over ssh -L
  pardes attach /run/x.sock:notes       through a socket forwarded already

See also: ps, kill, new --detach, the Detach word

== pardes help kill

End session NAME (its --9p or --detach name, else its pid) and its
shells: TERM, then KILL 2 s later. Unsaved changes are lost. --all
ends every session and every shell the daemon keeps.

Usage:
  pardes kill NAME

Examples:
  pardes kill notes                     the session started with --detach=notes
  pardes kill --all                     every session and shell

See also: ps, attach

== pardes help new

Start a session here, even in a pane of another: in this terminal for
pardes, a window for pardes-gui, or with --detach none until one
attaches. Bare `pardes` takes the same flags, and starts one unless
it is in a pane (where it hands its FILE to that session).

Usage:
  pardes new [flags] [FILE]

Flags:
  --tty                  start as one shell pane already in tty mode
  -n COUNT               shell panes to start with: 1 (default) or 3 (classic); a FILE boots just that file
  --tty-toggle KEY       Ctrl-KEY toggles tty and editor mode
  -l DUMP                load a dump of another instance (see Dump)
  --nested               a session of its own in a pane of another, serving none of its children
  --9p=NAME              name the 9P socket (else the --detach name, else the pid); under $XDG_RUNTIME_DIR, else ~/.local/state/pardes: a directory of yours alone
  --9p-tcp=tcp!IP!PORT   also serve 9P there, a numeric address
  --mount=NAME=DIAL      a 9P session or Unix/TCP endpoint under /n/NAME; repeat for more; os and self are reserved
  --geometry=WxH[+X+Y]   the window's size in points, and where it goes where the display lets a window say (X11)
  --detach[=NAME]        no terminal (no window) until one attaches; panes, shells and files stay; NAME (one path component) rather than the pid. One pardes --daemon per user keeps sessions (PARDES_DAEMON=off: none)
  -w, --wait             in a pane, hand FILE to its session and return once its pane is deleted: 0, or 1 if the session goes (EDITOR='pardes --wait')
  --                     the end of the flags: pardes -- -name opens -name

Examples:
  pardes new                            a session here, its shell pane in tty mode
  pardes new --detach=notes             one with no terminal, named notes
  pardes new -n 3 src/                  three shell panes in src/
  pardes new --mount=peer=notes         with session notes under /n/peer

See also: attach, kill, --nested

== pardes help do

Write WORD and its ARG to the ctl that takes it, as the session's
/commands says: the root's /ctl for a session's word, a pane's
pane/N/ctl for a pane's, that pane being this shell's ($PARDES_PANE)
or -p N. A refusal prints the session's own words, and the exit is 1.
The session is -s NAME, else $PARDES_9P, else the only one running.

Usage:
  pardes do WORD [ARG]

Examples:
  pardes do Newcol                      an empty column
  pardes do Save -p 3                   save pane 3
  pardes do Edit ',x/foo/c/bar/' -p 3   sam's Edit on pane 3
  pardes do Wrap -s notes               at session notes

See also: words, help WORD, /commands

== pardes help words

The session's builtins, as its /commands lists them, grouped by the
first key after the leader (SPC f is file, SPC c column): with no key,
a setting, a session's word (its root ctl's) or a text word (a
pane's). An addon's words are the addon group. With no session, the
ones this build has.

Usage:
  pardes words [GROUP]

Examples:
  pardes words                          every builtin, by group
  pardes words column                   the column words

See also: do, help WORD, /commands

== pardes help fs

The session's file tree, through a 9P client in this binary: the
files a mount or 9p(1) reaches, with a refusal in the session's own
words (a mount says only EINVAL). With no session, ls, stat, help and
complete, and a read of README, commands or ctl, ask a core made in
this process; the rest are a running session's, and say so.

Usage:
  pardes fs VERB [PATH]

usage: fs ls [PATH]              the names in a directory, a / after each directory
       fs read PATH              the file, to its end (a held read streams)
       fs write PATH [WORDS...]  the words and a newline, else stdin, as > would
       fs ask PATH WORDS...      write the words and read the answer on the same open
       fs follow PATH [WORDS...] ask, or read: what comes, as it comes, for as long
       fs stat PATH              mode length uid gid mtime name
       fs help [PATH]            what the tree's README says of PATH
       fs complete [PREFIX]      the paths that go on from PREFIX, for a shell

Examples:
  pardes fs ls pane/1                   what a pane serves
  pardes fs read index                  a line per pane
  pardes fs write pane/3/ctl 'Edit ,x/foo/c/bar/'  a write, refused in words
  pardes fs ask pane/3/pty/run make     exit N, then the output
  pardes fs follow log follow           events as they come

See also: help PATH, /README

== pardes help help

Bare, this map. A command: what it does, with examples. A builtin:
its /commands line, its key, and how to run it. A path of the tree:
what the tree's README says of it and of what is under it. --all:
every command's help and the README whole, as this build has them
(never a session's), which the reference prints.

Usage:
  pardes help [CMD|WORD|PATH]

Examples:
  pardes help attach                    a command
  pardes help Newcol                    a builtin
  pardes help pane/3/addr               a file of the tree

See also: words, fs help

== pardes help completion

A completion script for SHELL, printed, never installed. It asks this
binary back for each word (`pardes completion -- WORDS`): commands,
the builtins after do, sessions after attach and kill, the tree's
paths after fs.

Usage:
  pardes completion SHELL

Examples:
  pardes completion fish | source       in fish, for this shell
  source <(pardes completion bash)      in bash
  source <(pardes completion zsh)       in zsh

== pardes help skill

The guide for an agent that drives pardes, from this binary, so it
matches what it runs: recipes and traps. What is there it leaves to
`pardes help`.

Usage:
  pardes skill

Examples:
  pardes skill

== pardes help version

This build's version; the semantics a replica must share with its
session; the 9P its tree speaks.

Usage:
  pardes version

Examples:
  pardes version

== the old spellings

  --attach[=NAME]        pardes attach NAME
  --ps                   pardes ps
  --kill=NAME            pardes kill NAME
  --kill-all             pardes kill --all
  -h, --help             pardes help
  --version              pardes version

== pardes help /: the tree's README

Pardes virtual filesystem
=========================
README      this summary; the pardes book's Scripting and Reference chapters have the rest
index       a line per pane: serial kind(text|term|cmd|pdf|image|an addon's) dirty name column; names hold blanks: rsplit(maxsplit=1)
status      pid, version and pane count
look        write a line: a right click on it at the pane with the keyboard; read: the serials it touched (this open's)
exec        write a line: a middle click, a builtin or a shell line; read the same (every exec file)
pager       write a directory: its one +Pager, made or emptied; read the same open: its serial (pardes -)
log         events: new del rename save newcol delcol run exit send ask answer changed dump restore restored restoredcol msg err
screen      the rendered screen as JSON, frozen from open to close
listeners   the session's dial addresses
sessions    the pardes daemon's, as pardes --ps: daemon <pid>; session <pid> tty|gui attached|detached <name>; shell <pid>; orphan <pid>
focus       the serial of the pane with the keyboard (empty on a column tag); write one to give it the keyboard
kbdin       write runes: keys typed at the pane with the keyboard, done before the write answers (\x1b Esc, \n Enter)
mousein     write `m col row buttons` (1 left, 2 middle, 4 right): the mouse as it now is; m 10 5 4, m 10 5 0 is a right click
ctl         settings a line; or Newcol, Dump [export f], Restore [label|f], Exit (refuses once over unsaved panes), Kill [w], size C R
commands    every builtin: word, arg, root|pane|both (the ctl that takes it), -- what it does; addons: the kinds of pane here
recent      files opened lately, closed ones too: open|closed <path>
dumps       the dumps the state file keeps, the newest first: <label> <date> <size> <panes>
layout      a line per column: serial index x width current|notcurrent empty|full pane-serials; then active <serial>
tag         the workspace tag, tagexec a word as a click in it; col/<serial>/ a column's tag, ctl, exec; rmdir: empty only
plumb/      rules: the plumber's rules, plumb(6)'s (a write adds rule sets, > replaces); send: write a message, six lines then data; <port>: read the messages sent to it
pane/new    open it to make a pane (<session dir>/+New) in the active column; the read answers its serial
pane/<n>/   name body tag ctl addr dot limit data xdata sel dirty mark scroll errors event look exec tagexec rows; rmdir closes
            rows: a line a row, kind (m c p; d decl, u unmarked) line col end_line end_col source_column location_end code_start styles path; styles - or N:start+len=role,... (keyword string number comment, add del emph line, joined by .); a write at 0 replaces
            on terminals pty/data (keys in, output out), pty/status, pty/ctl (winsize, sig, exec), pty/run (a line, its exit and output)
os/         the host filesystem
$m below: $PARDES_MOUNT (set under 9ns --mntgen); without it, 9p -a "unix!$PARDES_9P".
  cat $m/index                                 which panes exist
  n=$(cat $m/pane/new)                         make a pane of your own (each open makes one), take its serial
  exec 3<>$m/pane/$n/look; echo /etc/hosts:3 >&3; cat <&3   open a file through it, see the pane it went to
  printf 'text\n' >> $m/pane/$n/body           append to it (> replaces it all)
  echo 'Msg hello' > $m/pane/$n/exec           show text in the editor
  echo 'Edit ,x/foo/c/bar/' > $m/pane/$n/ctl   sam's Edit, one undo step; an x that matches nothing succeeds
  echo /re/ > $m/pane/$n/addr; printf new > $m/pane/$n/data   replace the next match
  exec 3<>$m/log; echo follow >&3; cat <&3     what happened lately, then wait for more
  exec 3<>$m/pane/$n/pty/run; echo make >&3; cat <&3   exit N, then the output

Traps:
  A refused write says only EINVAL or EIO; grep '^err' log | tail -1 says why (not the last line, maybe +Unsaved's new).
  Root look and exec act at the pane with the keyboard, which another client may own: use a pane's own look and exec.
  addr is the pane's and moves on: each /re/ searches from the last, a data write leaves it past the text.
  Through a mount, printf 'a\nb\n' arrives a line a write: send a block with one write, ending in a newline.
  Pane words (Save Undo Del) go to pane/<n>/ctl, settings and session words to /ctl.
  Exit, Restore, Del and get refuse once over unsaved text; the same word again discards.