diff -r 32430612b929 -r 8fdaf5e1f8fc configuration.md
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/configuration.md	Sun May 14 11:18:58 2017 +0200
@@ -0,0 +1,72 @@
+# 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 configuration file is usually located in the `$HOME/.config/madonctl`
+directory.
+
+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
+```
+
+## 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) - optional
+`password`  | User password - optional
+`safe_mode` | If set to `true`, the configuration cannot be dumped with *config dump*
+`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