commands.org
... ...
@@ -12,11 +12,9 @@ title: Commands | Pluckeye
12 12
[[_TOC_|levels = 1]]
13 13
14 14
* + (add)
15
- Usage: ~pluck + [rule]~
16
-
17
- Adds a rule to your configuration or enables a feature.
18 15
19 16
** Examples
17
+
20 18
To add an [[rules#allow][allow]] rule:
21 19
22 20
#+BEGIN_SRC sh
... ...
@@ -33,14 +31,16 @@ title: Commands | Pluckeye
33 31
pluck + system
34 32
#+END_SRC
35 33
36
-* - (minus)
37
- Usage: ~pluck - [rule]~
34
+** Description
38 35
39
- Removes a rule from your configuration or disables a feature. For example, if you delete a ~block~ rule for a given site, Pluckeye reverts to the default setting of blocking images and video while allowing pages to otherwise load. (An exception to this rule occurs if you have changed the default `block image/`, `block video/`, or if you have conflicting rules already in place. For example, if you have ~allow google.com~ and ~block google.com~, the block rule overrides the allow rule. If the block rule is deleted, the allow rule succeeds. If the allow rule is also deleted, the default rule succeeds and blocks images and video while allowing the site to otherwise load.)
36
+ Adds a rule to your configuration or enables a feature.
40 37
41
- If you attempt to remove a rule that is not in your configuration, this command does nothing.
38
+ Usage: ~pluck + [rule]~
39
+
40
+* - (minus)
42 41
43 42
** Examples
43
+
44 44
To remove an [[rules#allow][allow]] rule:
45 45
46 46
#+BEGIN_SRC sh
... ...
@@ -59,12 +59,18 @@ title: Commands | Pluckeye
59 59
pluck - nhb
60 60
#+END_SRC
61 61
62
-* abort
63
- Usage: ~pluck abort [context]~
62
+** Description
63
+
64
+ Removes a rule from your configuration or disables a feature. For example, if you delete a ~block~ rule for a given site, Pluckeye reverts to the default setting of blocking images and video while allowing pages to otherwise load. (An exception to this rule occurs if you have changed the default `block image/`, `block video/`, or if you have conflicting rules already in place. For example, if you have ~allow google.com~ and ~block google.com~, the block rule overrides the allow rule. If the block rule is deleted, the allow rule succeeds. If the allow rule is also deleted, the default rule succeeds and blocks images and video while allowing the site to otherwise load.)
65
+
66
+ If you attempt to remove a rule that is not in your configuration, this command does nothing.
64 67
65
- Aborts pending rule changes (those that will take effect once the delay has elapsed). By default all pending rule changes are removed. If a website, page, program, etc. is given, all pending changes that match that context are removed.
68
+ Usage: ~pluck - [rule]~
69
+
70
+* abort
66 71
67 72
** Examples
73
+
68 74
In all of the following examples a rule change is entered, but the rule never comes into effect if you have a non-zero [[delay]], because the change is aborted.
69 75
70 76
#+BEGIN_SRC sh
... ...
@@ -82,39 +88,46 @@ title: Commands | Pluckeye
82 88
pluck abort image
83 89
#+END_SRC
84 90
91
+** Description
92
+
93
+ Aborts pending rule changes (those that will take effect once the delay has elapsed). By default all pending rule changes are removed. If a website, page, program, etc. is given, all pending changes that match that context are removed.
94
+
95
+ Usage: ~pluck abort [context]~
96
+
85 97
* approved?
86
- Usage: ~pluck approved?~
87 98
88 99
Fetches [[glossary#expedite][expedite]] approvals from [[//u.pluckeye.net/][the users site]]. Currently it is necessary to run this after one of your supporters has approved one of your expedite requests, in order for the change to take effect on your device. Hopefully this will be automatic in the future.
89 100
101
+ Usage: ~pluck approved?~
102
+
90 103
* clear
91
- Usage: ~pluck clear~
92 104
93 105
Removes /all/ Pluckeye rules, meaning you will have full Internet access after your [[delay]] elapses. It makes sense to run this once after you first install Pluckeye if you want Pluckeye to only block a few websites, and allow all access otherwise. There is no way to automatically go back to the configuration you had after running this. If you want to save your existing configuration so you can restore it later, you can use [[#export][export]] to do this.
94 106
95 107
/See also: [[rules#everything][allow everything]]/
96 108
109
+ Usage: ~pluck clear~
110
+
97 111
* compact
98
- Usage: ~pluck compact~
99 112
100 113
A maintenance command to shrink data.
101 114
115
+ Usage: ~pluck compact~
116
+
102 117
* delay
118
+
103 119
/Main article: [[delay]]/
104 120
105 121
* delays
106
- Usage: ~pluck delays~
107 122
108 123
Prints the current delay, and also [[delay#delay-patterns-advanced-pluckeye-1-0][non-standard delays]] that apply to specific websites, pages, programs, etc.
109 124
110
-* eval
111
- Usage: ~pluck eval [-x] <context>~
112
-
113
- Evaluates whether a given website, page, program, etc. is allowed according to your current configuration. It can be used to troubleshoot why something is or isn't being displayed. Note that merely giving a website will tell you whether the website will load, not whether images or video on the website are allowed. (See the examples.)
125
+ Usage: ~pluck delays~
114 126
115
- By default, the command has an exit code of 0 unless an error occurs. If the ~-x~ flag is used, the command will have an exit code of 0 if the result was ~allow~ or ~null~, and a non-zero exit code if it was ~block~. (If you have no idea what this means, then you have no use for the ~-x~ flag.) This is mainly useful in scripts.
127
+* eval
116 128
117 129
** Examples
130
+
118 131
The output you see when you run this command will depend on your Pluckeye configuration; the default configuration produces outputs similar to the ones shown here.
119 132
120 133
Input (what you type):
... ...
@@ -143,12 +156,18 @@ title: Commands | Pluckeye
143 156
block because of rule 420: block image/
144 157
#+END_EXAMPLE
145 158
146
-* export
147
- Usage: ~pluck export~
159
+** Description
148 160
149
- Prints your Pluckeye configuration and any pending changes to it. (In technical terms, it prints all of the rules in your Pluckeye configuration and all pending rule changes to standard output.) You can also use it (as shown in the examples) to save your configuration in a file.
161
+ Evaluates whether a given website, page, program, etc. is allowed according to your current configuration. It can be used to troubleshoot why something is or isn't being displayed. Note that merely giving a website will tell you whether the website will load, not whether images or video on the website are allowed. (See the examples.)
162
+
163
+ By default, the command has an exit code of 0 unless an error occurs. If the ~-x~ flag is used, the command will have an exit code of 0 if the result was ~allow~ or ~null~, and a non-zero exit code if it was ~block~. (If you have no idea what this means, then you have no use for the ~-x~ flag.) This is mainly useful in scripts.
164
+
165
+ Usage: ~pluck eval [-x] <context>~
166
+
167
+* export
150 168
151 169
** Examples
170
+
152 171
All of these examples demonstrate how to create a file on your Desktop that contains your Pluckeye configuration.
153 172
154 173
*** Windows
... ...
@@ -165,24 +184,28 @@ title: Commands | Pluckeye
165 184
pluck export > pluckeye-configuration.txt
166 185
#+END_SRC
167 186
187
+** Description
188
+
189
+ Prints your Pluckeye configuration and any pending changes to it. (In technical terms, it prints all of the rules in your Pluckeye configuration and all pending rule changes to standard output.) You can also use it (as shown in the examples) to save your configuration in a file.
190
+
191
+ Usage: ~pluck export~
192
+
168 193
* factoryreset
169
- Usage: ~pluck factoryreset~
170 194
171 195
Resets Pluckeye to its "factory" settings (i.e., as if you had just installed for the first time). Your current configuration /will be lost/. If you plan to reuse or restore your current configuration, make sure you [[#export][export]] and save it to a configuration file before performing the factory reset.
172 196
197
+ Usage: ~pluck factoryreset~
198
+
173 199
* features
174
- Usage: ~pluck features~
175 200
176 201
Prints enabled [[features]], such as [[#system][system]] and [[#nhb][nhb]].
177 202
178
-* find
179
- Usage: ~pluck find <term(s)>~
180
-
181
- /This feature was added to Pluckeye in versoin 1.0, so if you are using an older version of Pluckeye, this will not work for you./
203
+ Usage: ~pluck features~
182 204
183
- Print rules in your configuration that match the given term(s). (In more technical terms, if any of the terms is a substring of a given rule, that rule is printed.)
205
+* find
184 206
185 207
** Examples
208
+
186 209
The output of this command will depend on your Pluckeye configuration; the default configuration produced the outputs shown here.
187 210
188 211
This example will give no output, since none of the rules in the default configuration contain "google.com".
... ...
@@ -204,13 +227,21 @@ title: Commands | Pluckeye
204 227
block image/
205 228
#+END_EXAMPLE
206 229
230
+** Description
231
+
232
+ /This feature was added to Pluckeye in versoin 1.0, so if you are using an older version of Pluckeye, this will not work for you./
233
+
234
+ Print rules in your configuration that match the given term(s). (In more technical terms, if any of the terms is a substring of a given rule, that rule is printed.)
235
+
236
+ Usage: ~pluck find <term(s)>~
237
+
207 238
* future
208
- Usage: ~pluck future~
209 239
210 240
Prints all pending changes to your configuration.
211 241
242
+ Usage: ~pluck future~
243
+
212 244
* help
213
- Usage: ~pluck --help~ or ~pluck help~
214 245
215 246
Prints usage and examples for basic Pluckeye commands. In v1.0.23 it reads:
216 247
... ...
@@ -232,10 +263,9 @@ title: Commands | Pluckeye
232 263
233 264
/See also: [[#more-help][more-help]]/
234 265
235
-* import
236
- Usage: ~pluck import [configuration file]~
266
+ Usage: ~pluck --help~ or ~pluck help~
237 267
238
- Overrides current configuration and imports a configuration file. The configuration file should contain a list of Pluckeye rules, with one rule per line. Lines starting with ~#~ will be ignored, so it can be used to add comments.
268
+* import
239 269
240 270
** Examples
241 271
Before running this command, first open the terminal in the directory (AKA folder) containing the pluckeye-configuration.txt file that you want to import.
... ...
@@ -244,10 +274,13 @@ title: Commands | Pluckeye
244 274
pluck import pluckeye-configuration.txt
245 275
#+END_SRC
246 276
247
-* import-allow
248
- Usage: ~pluck import-allow [context file]~
277
+** Description
278
+
279
+ Overrides current configuration and imports a configuration file. The configuration file should contain a list of Pluckeye rules, with one rule per line. Lines starting with ~#~ will be ignored, so it can be used to add comments.
249 280
250
- Similar to ~import~, but the file should contain a list of websites, pages, programs, etc. An `allow` rule will be added to your configuration for each one of these. This is equivalent to running ~pluck + allow [line]~ for every line in the context file, except that lines starting with ~#~ in the context file will be ignored.
281
+ Usage: ~pluck import [configuration file]~
282
+
283
+* import-allow
251 284
252 285
** Examples
253 286
... ...
@@ -263,10 +296,13 @@ In good-websites.txt, there could be:
263 296
https://youtube.com/watch
264 297
#+END_EXAMPLE
265 298
266
-* import-block
267
- Usage: ~pluck import-block [context file]~
299
+** Description
268 300
269
- Similar to [[#import-allow][import-allow]], but all of the websites, pages, programs, etc. in the context file will be blocked.
301
+ Similar to ~import~, but the file should contain a list of websites, pages, programs, etc., and an `allow` rule will be added to your configuration for each one of these. This is equivalent to running ~pluck + allow [line]~ for every line in the context file, except that lines starting with ~#~ in the context file will be ignored.
302
+
303
+ Usage: ~pluck import-allow [context file]~
304
+
305
+* import-block
270 306
271 307
** Examples
272 308
... ...
@@ -274,15 +310,19 @@ In good-websites.txt, there could be:
274 310
pluck import-block bad-websites.txt
275 311
#+END_SRC
276 312
313
+** Description
314
+
315
+ Similar to [[#import-allow][import-allow]], but all of the websites, pages, programs, etc. in the context file will be blocked.
316
+
317
+ Usage: ~pluck import-block [context file]~
318
+
277 319
* mayprove
278
- Usage: ~pluck mayprove~
279 320
280 321
Synonym for [[#approved][approved?]].
281 322
282
-* mety
283
- Usage: ~pluck mety .<extension>~
323
+ Usage: ~pluck mayprove~
284 324
285
- Prints the [[media-types][media type]] for the specified extension.
325
+* mety
286 326
287 327
** Examples
288 328
... ...
@@ -300,89 +340,112 @@ In good-websites.txt, there could be:
300 340
301 341
/See also: [[media-types][Media types]]/
302 342
343
+** Description
344
+
345
+ Prints the [[media-types][media type]] for the specified extension.
346
+
347
+ Usage: ~pluck mety .<extension>~
348
+
303 349
* more-help
304
- Usage: ~pluck --more-help~ or ~pluck more-help~
305 350
306 351
Prints usage and examples for many Pluckeye commands.
307 352
308 353
/See also: [[#help][help]]/
309 354
355
+ Usage: ~pluck --more-help~ or ~pluck more-help~
356
+
310 357
* refresh
311
- Usage: ~pluck refresh~
312 358
313 359
Refetches configurations from [[//u.pluckeye.net/][the users site]]. If you don't know what this means, check out [[synchronizing-configurations][Synchronizing configurations]].
314 360
315 361
/See also: [[#sync][sync]]/
316 362
363
+ Usage: ~pluck refresh~
364
+
317 365
* repair
318
- Usage: ~pluck repair~
319 366
320 367
Attempts to repair Internet access.
321 368
322
-* replace
323
- Usage: ~pluck replace <string0> <string1>~
369
+ Usage: ~pluck repair~
324 370
325
- This more technically advanced command reads standard input, replaces all instances of string0 with string 1, and prints the result on standard output. This is useful when pipelining.
371
+* replace
326 372
327 373
** Examples
374
+
328 375
This pipeline finds all rules in your configuration that contain "example.com", replaces "allow" with "when now+5m block" in all of the rules, and then imports these new rules into your configuration. The point is to cause all content on example.com that was allowed by ~allow~ rules before to be blocked for the next five minutes.
329 376
330 377
#+BEGIN_SRC sh
331 378
pluck find example.com | pluck replace allow "when now+5m block" | pluck import -
332 379
#+END_SRC
333 380
381
+** Description
382
+
383
+ This more technically advanced command reads standard input, replaces all instances of string0 with string 1, and prints the result on standard output. This is useful when pipelining.
384
+
385
+ Usage: ~pluck replace <string0> <string1>~
386
+
334 387
* supplicate
335
- Usage: ~pluck supplicate~
336 388
337 389
Sends expedite requests to [[//u.pluckeye.net/][the users site]] so that someone else can approve them.
338 390
391
+ Usage: ~pluck supplicate~
392
+
339 393
* sync
340
- Usage: ~pluck sync~
341 394
342 395
Synchronizes your device's configuration with the one assigned to it on [[//u.pluckeye.net/][the users site]]. If you don't know what this means, check out [[synchronizing-configurations][Synchronizing configurations]].
343 396
344 397
/See also: [[#refresh][refresh]]/
345 398
399
+ Usage: ~pluck sync~
400
+
346 401
* trim
347
- Usage: ~pluck trim~
348 402
349 403
A maintenance command to shrink data.
350 404
405
+ Usage: ~pluck trim~
406
+
351 407
* unimport
352
- Usage: ~pluck unimport [configuration file]~
353 408
354 409
Similar to import, except that it removes all of the rules in the configuration file instead of adding them.
355 410
411
+ Usage: ~pluck unimport [configuration file]~
412
+
356 413
* unimport-allow
357
- Usage: ~pluck unimport-allow [context file]~
358 414
359 415
Similar to [[#import-allow][import-allow]], except that it removes ~allow~ rules for each of the websites, pages, programs, etc. in the context file instead of adding them.
360 416
417
+ Usage: ~pluck unimport-allow [context file]~
418
+
361 419
* unimport-block
362
- Usage: ~pluck unimport-block [context file]~
363 420
364 421
Similar to [[#import-block][import-block]], except that it removes ~block~ rules for each of the websites, pages, programs, etc. in the context file instead of adding them.
365 422
423
+ Usage: ~pluck unimport-block [context file]~
424
+
366 425
* uninstall
367
- Usage: ~pluck uninstall~
368 426
369 427
Uninstalls Pluckeye. The delay must be 0 before you do this.
370 428
429
+ Usage: ~pluck uninstall~
430
+
371 431
* upload
372
- Usage: ~pluck upload~
373 432
374 433
Upload your local configurations to [[//u.pluckeye.net/][the users site]]. See [[synchronizing-configurations][Synchronizing configurations]] for more info.
375 434
435
+ Usage: ~pluck upload~
436
+
376 437
* verdicts
377
- Usage: ~pluck verdicts~
378 438
379 439
Print recent Internet connection attempts and whether Pluckeye allowed or blocked them.
380 440
441
+ Usage: ~pluck verdicts~
442
+
381 443
* version
382
- Usage: ~pluck version~
383 444
384 445
Print the version of Pluckeye that is installed.
385 446
447
+ Usage: ~pluck version~
448
+
386 449
* Legacy
387 450
These commands are outdated, but were used in older versions of Pluckeye.
388 451
... ...
@@ -393,18 +456,20 @@ In good-websites.txt, there could be:
393 456
Replaced by [[#minus][- (minus)]], which works the same way.
394 457
395 458
** level
396
- Usage: ~pluck level [new level]~
397 459
398 460
Sets the level. Replaced by the [[system][system feature]].
399 461
462
+ Usage: ~pluck level [new level]~
463
+
400 464
** rm
401 465
Replaced by [[#minus][- (minus)]], which works the same way.
402 466
403 467
** set
404
- # Org-ruby (what Gollum uses to convert Org-mode to HMTL) doesn't properly handle quotes inside ~'s. See https://github.com/wallyqs/org-ruby/issues/36
405
- Usage: pluck set "delay <new delay>"
406 468
407 469
Sets the delay. Replaced by [[#delay][delay]].
408 470
471
+ # Org-ruby (what Gollum uses to convert Org-mode to HMTL) doesn't properly handle quotes inside ~'s. See https://github.com/wallyqs/org-ruby/issues/36
472
+ Usage: pluck set "delay <new delay>"
473
+
409 474
** unbork
410 475
Replaced by [[#repair][repair]].