author | Mikael Berthe <mikael@lilotux.net> |
Wed, 21 Mar 2018 23:53:59 +0100 | |
changeset 215 | b0bc0a131b59 |
parent 143 | abfa3aa97b51 |
child 231 | d5b3fb928f0f |
permissions | -rw-r--r-- |
137
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
1 |
# Configuration |
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
2 |
|
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
3 |
In order to use madonctl, you need to specify the instance name or URL, and |
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
4 |
usually at least provide an account login/password (or a token). |
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
5 |
|
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
6 |
These settings can be passed as command line arguments or environment variables, |
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
7 |
but the easiest way is to use a configuration file. |
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
8 |
|
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
9 |
Note that every variable from the configration file can also be set with an |
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
10 |
environment variable (e.g. `export MADONCTL_INSTANCE='https://mamot.fr'`). |
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
11 |
|
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
12 |
## Configuration file |
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
13 |
|
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
14 |
The configuration file is usually located in the `$HOME/.config/madonctl` |
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
15 |
directory. |
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
16 |
|
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
17 |
We use [viper](http://spf13.com/project/viper), so you can use the format you |
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
18 |
prefer between YAML, TOML or JSON. The examples use the YAML format so the |
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
19 |
configuration file will be named `madonctl.yaml`. |
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
20 |
|
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
21 |
You can generate a sample configuration file for your settings with |
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
22 |
``` sh |
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
23 |
madonctl config dump -i mastodon.social -L username@domain -P password |
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
24 |
``` |
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
25 |
|
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
26 |
The output of this command can be redirected to a file: |
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
27 |
``` sh |
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
28 |
madonctl config dump -i mstn.io -L email -P passw > madonctl.yaml |
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
29 |
``` |
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
30 |
|
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
31 |
If you only provide the Mastodon instance, it will generate a configuration |
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
32 |
file with an application ID/secret for this instance and you will have to add |
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
33 |
the user credentials. |
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
34 |
|
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
35 |
If you don't want to use the password or if you have enabled *Two-factor |
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
36 |
authentication*, you can use **OAuth2** with the `oauth2` command, either |
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
37 |
interactively or non-interactively: |
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
38 |
|
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
39 |
`madonctl -i mastodon.social oauth2` |
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
40 |
|
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
41 |
The output is similar to the previous `config dump` command, so you can create |
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
42 |
your configuration file like this as well: |
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
43 |
|
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
44 |
`madonctl -i mastodon.social oauth2 > madonctl.yaml` |
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
45 |
|
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
46 |
Note: If don't want to use the tool interactively, check to `get-url` and `code` |
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
47 |
subcommands: |
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
48 |
``` sh |
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
49 |
madonctl -i mastodon.social oauth2 get-url |
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
50 |
# (Paste the link into your browser...) |
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
51 |
madonctl -i mastodon.social code $CODE > config_file.yaml |
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
52 |
``` |
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
53 |
|
143 | 54 |
Note that if you have set up madonctl to use a default theme, you will have |
55 |
to force the output with `-o plain` to get the example configuration file. |
|
56 |
||
137
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
57 |
## Settings |
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
58 |
|
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
59 |
All the available settings should be displayed with *config dump* (assuming |
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
60 |
the *safe_mode* variable is not set). |
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
61 |
|
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
62 |
Option | Description |
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
63 |
------ | ----------- |
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
64 |
`instance` | Name of the Mastodon instance (e.g. 'mastodon.social') |
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
65 |
`app_id` | Application ID (generated by madonctl) |
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
66 |
`app_secret`| Application secret (generated by madonctl) |
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
67 |
`token` | User Mastodon token (generated at login time) |
139 | 68 |
`login` | User login (email) |
69 |
`password` | User password |
|
70 |
`safe_mode` | If set to *true*, the configuration cannot be dumped with *config dump* |
|
142
b0d55f7fddeb
Add default_visibility to configuration documentation
Mikael Berthe <mikael@lilotux.net>
parents:
139
diff
changeset
|
71 |
`default_visibility` | Default toots visibillity (Mastodon's default is 'public') |
137
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
72 |
`default_output` | Default output format; one of plain, yaml, json or theme |
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
73 |
`template_directory` | The local directory where templates and themes are installed |
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
74 |
`default_theme` | Default theme name (e.g. *ansi*) |
8fdaf5e1f8fc
Add configration.md with settings details
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
75 |
`color` | Default color setting (on, off, auto) |
139 | 76 |
`verbose` | Set to *true* for verbose mode |
77 |
||
78 |
Note that if a token is set, the login and the password are not necessary.\ |
|
79 |
It is recommended to reuse the same token (and it will be faster). |