# Configuration

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

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

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

but the easiest way is to use a configuration file.

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

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

## Configuration file

The default configuration file is located at `$HOME/.config/madonctl/madonctl.yaml`.

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

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

configuration file will be named `madonctl.yaml`.

You can generate a sample configuration file for your settings with

``` sh

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

```

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

``` sh

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

```

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

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

the user credentials.

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

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

interactively or non-interactively:

`madonctl -i mastodon.social oauth2`

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

your configuration file like this as well:

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

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

subcommands:

``` sh

madonctl -i mastodon.social oauth2 get-url

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

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

```

Note that if you have set up madonctl to use a default theme, you will have

to force the output with `-o plain` to get the example configuration file.

## Settings

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

the *safe_mode* variable is not set).

Option | Description

------ | -----------

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

`app_id`    | Application ID (generated by madonctl)

`app_secret`| Application secret (generated by madonctl)

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

`login`     | User login (email)

`password`  | User password

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

`default_visibility` | Default toots visibillity (Mastodon's default is 'public')

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

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

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

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

`verbose`            | Set to *true* for verbose mode

Note that if a token is set, the login and the password are not necessary.\

It is recommended to reuse the same token (and it will be faster).