1 # Configuration

     2 

     3 In order to use madonctl, you need to specify the instance name or URL, and

     4 usually at least provide an account login/password (or a token).

     5 

     6 These settings can be passed as command line arguments or environment variables,

     7 but the easiest way is to use a configuration file.

     8 

     9 Note that every variable from the configration file can also be set with an

    10 environment variable (e.g. `export MADONCTL_INSTANCE='https://mamot.fr'`).

    11 

    12 ## Configuration file

    13 

    14 The configuration file is usually located in the `$HOME/.config/madonctl`

    15 directory.

    16 

    17 We use [viper](http://spf13.com/project/viper), so you can use the format you

    18 prefer between YAML, TOML or JSON.  The examples use the YAML format so the

    19 configuration file will be named `madonctl.yaml`.

    20 

    21 You can generate a sample configuration file for your settings with

    22 ``` sh

    23 madonctl config dump -i mastodon.social -L username@domain -P password

    24 ```

    25 

    26 The output of this command can be redirected to a file:

    27 ``` sh

    28 madonctl config dump -i mstn.io -L email -P passw > madonctl.yaml

    29 ```

    30 

    31 If you only provide the Mastodon instance, it will generate a configuration

    32 file with an application ID/secret for this instance and you will have to add

    33 the user credentials.

    34 

    35 If you don't want to use the password or if you have enabled *Two-factor

    36 authentication*, you can use **OAuth2** with the `oauth2` command, either

    37 interactively or non-interactively:

    38 

    39 `madonctl -i mastodon.social oauth2`

    40 

    41 The output is similar to the previous `config dump` command, so you can create

    42 your configuration file like this as well:

    43 

    44 `madonctl -i mastodon.social oauth2 > madonctl.yaml`

    45 

    46 Note: If don't want to use the tool interactively, check to `get-url` and `code`

    47 subcommands:

    48 ``` sh

    49 madonctl -i mastodon.social oauth2 get-url

    50 # (Paste the link into your browser...)

    51 madonctl -i mastodon.social code $CODE > config_file.yaml

    52 ```

    53 

    54 ## Settings

    55 

    56 All the available settings should be displayed with *config dump* (assuming

    57 the *safe_mode* variable is not set).

    58 

    59 Option | Description

    60 ------ | -----------

    61 `instance`  | Name of the Mastodon instance (e.g. 'mastodon.social')

    62 `app_id`    | Application ID (generated by madonctl)

    63 `app_secret`| Application secret (generated by madonctl)

    64 `token`     | User Mastodon token (generated at login time)

    65 `login`     | User login (email) - optional

    66 `password`  | User password - optional

    67 `safe_mode` | If set to `true`, the configuration cannot be dumped with *config dump*

    68 `default_output`     | Default output format; one of plain, yaml, json or theme

    69 `template_directory` | The local directory where templates and themes are installed

    70 `default_theme`      | Default theme name (e.g. *ansi*)

    71 `color`              | Default color setting (on, off, auto)

    72 `verbose`            | Set to true for verbose mode