Mercurial > libervia-backend

comparison doc/libervia-cli/shell.rst @ 3488:c80a0f864b5d

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc: updated doc following global renaming
author Goffi <goffi@goffi.org>
date Sun, 21 Mar 2021 18:23:58 +0100
parents doc/jp/shell.rst@9464ad3b2ece
children 4705f80b6e23
comparison
equal deleted inserted replaced
3487:75427f0a5445 3488:c80a0f864b5d
1 ========================
2 shell: use SàT with REPL
3 ========================
4
5 ``shell`` launch a read–eval–print loop (REPL) with some helpers to launch li commands.
6 This is useful if you are willing to a session when you'll use several commands in a row
7 (for e.g. to inspect something on a PubSub service).
8
9 start the shell
10 ===============
11
12 To start the shell, you just have to enter ``li shell``. You can eventually specify a
13 profile to use an other one than the default one by entering ``li shell -p
14 <some_profile>``.
15
16
17 .. _libervia-cli_shell_use:
18
19 use the shell
20 =============
21
22 Once in the shell, you can launch a command by entering it as usual (without having to
23 specify ``li``). For instance to get last 2 blog posts from your personal blog, you just
24 have to enter::
25
26 > blog get -m 2
27
28 There are 2 kinds of commands in the shell:
29
30 - **shell commands** which are command to manipulate the shell itself
31 - **li commands** which are the classic commands that you use with li
32
33 The most important thing to remember is that you can use ``?`` (or ``help`` which is
34 equivalent) to get the list of commands (shell + li), and ``?<command>`` (or ``help
35 <command>``) to get information on a shell command. For li commands, you can use the usual
36 ``--help`` argument.
37
38 You may move in the commands hierarchy using ``cmd`` which can be seen as something
39 roughly equivalent to ``cd`` for the filesystem. for instance if you know you'll work with
40 XMPP blogs, you can enter::
41
42 > cmd blog
43
44 Then you'll be in the blog hierarchy, you can check that by entering ``?``. From there you
45 can use blog commands directly, like in this example to retrieve last 2 blog posts::
46
47 blog> get -m 2
48
49 You can even go further, e.g. if you know that you'll do several ``get`` command (in this
50 can you'll only have to specify the arguments of ``get``)::
51
52 blob> cmd get
53 blog/get> -m 2
54
55 You can use ``/`` with ``cmd``, including as first character to indicate that you want to
56 start from root::
57
58 blog/get> cmd /pubsub
59 pubsub> cmd node/info
60
61 Similarly, you can use ``..`` to move to parent command::
62
63 pubsub/node/info> cmd ..
64
65 One of the interesting feature of shell is that you can fix an argument, i.e. indicate
66 the value to use in the next commands. For instance if you're willing to work on a
67 specific node, you can set its value with ``use``::
68
69 blog> use node some_interesting_node
70
71 Then you won't have to specify it anymore for each command. The name of the argument to
72 fix must be the long form. To check which arguments are fixed, just enter ``use`` without
73 argument. If an argument is fixed but not used in a command, it will be ignored.
74
75 To clear a fixed argument, you have the ``use_clear`` command. To clear the ``node``
76 argument set above, just enter::
77
78 blog> use_clear node
79
80 Without argument, all fixed arguments will be cleared.
81
82
83 Shell commands
84 ==============
85
86 Below is a description of shell commands.
87
88
89 cmd
90 ---
91
92 Move in the command hierarchy, this avoid to type again a command if you know you'll use
93 it several times. See libervia-cli_shell_use_ for explanation and examples
94
95 do
96 --
97
98 Launch a li command. By default the command is launched if you enter directly its name and
99 arguments, but if a command or argument conflict with a shell command, the shell command
100 will be launched instead. The ``do`` command avoid such a situation by always launching a
101 li command::
102
103 > do blog get -m 2
104
105 exit
106 ----
107
108 Quit the shell (alias of ``quit``).
109
110 help (alias ``?``)
111 ------------------
112
113 Give information on available commands or on a specific command, see libervia-cli_shell_use_ for
114 more explanations.
115
116 examples
117 ^^^^^^^^
118
119 Get general help::
120
121 > ?
122
123 Get help on ``do`` command::
124
125 > ?do
126
127 quit
128 ----
129
130 Quit the shell
131
132 shell (alias ``!``)
133 -------------------
134
135 Launch an external command.
136
137 example
138 ^^^^^^^
139
140 Print a calendar with ``cal``::
141
142 > !cal
143
144 use
145 ---
146
147 Fix the value of an argument, which will then be set for all following commands, see
148 libervia-cli_shell_use_ for more explanations.
149
150 Without argument, show all fixed arguments
151
152 examples
153 ^^^^^^^^
154
155 Fix the PubSub node (the long name of the argument is used, so it will go to ``--node``)::
156
157 pubsub> use node some_intersting_node
158
159 Show all fixed arguments::
160
161 > use
162
163 use_clear
164 ---------
165
166 Unfix the value of an argument (i.e. use the normal default value). Without argument,
167 it unfixes all arguments.
168
169 examples
170 ^^^^^^^^
171 Clear the node::
172
173 pubsub> use_clear node
174
175 Clear all arguments::
176
177 > use_clear
178
179 verbose
180 -------
181
182 Without argument, show if verbose mode is activated. With an argument evaluating to a
183 boolean, activate or deactivate this mode.
184
185 In verbose mode, the fixed arguments and the command launched are printed before launching
186 a li command.
187
188 examples
189 ^^^^^^^^
190
191 Show if verbose mode is activated::
192
193 > verbose
194
195 Activate verbose mode::
196
197 > verbose on
198
199 version
200 -------
201
202 Print current version of li/Salut à Toi.
203
204 whoami
205 ------
206
207 Show the name of the connected profile (the one set with ``--profile`` when launching the
208 shell). This profile will be used as default profile.