About madonctl

madonctl is a command line client for the Mastodon distributed social network API.

The Mastodon 1.3 API has a 100% coverage.

madonctl uses the Madon Golang Mastodon API library implementation.


The autogenerated manual pages are online there (you might want to browse the html version).
You can also use the built-in help command.


You can get some pre-built binaries available for different OSes/platforms on Github release page (or here, but it will be much slower).

madonctl is written in go (Golang), the source code is available on github (I also have a Mercurial mirror).

If you have Go 1.7+ installed, you can install madonctl with the following command: go get -u github.com/McKael/madonctl


In order to use madonctl, you need to specify the instance name or URL, and usually 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.

You can generate a configuration file for your settings with
madonctl config dump -i mastodon.social -L username@domain -P password
(You can redirect the output to the configuration file.)


Check the Github README for many more examples (the examples below might be outdated).
% madonctl toot "Hello, World"
% madonctl toot --visibility direct "@McKael Hello, you"
% madonctl toot --visibility private --spoiler CW "The answer was 42"
% madonctl post --file image.jpg Selfie # Send a media file
% madonctl accounts blocked             # List blocked accounts
% madonctl accounts muted               # List muted accounts
% madonctl account notifications --list --clear # List and clear notifications
% madonctl status --status-id 416671 favourite  # Fave a status
% madonctl status --status-id 416671 boost      # Boost a status
% madonctl account follow Gargron@mastodon.social

% madonctl account show           # Display an account
% madonctl account show -o yaml   # Display an account, in yaml
% madonctl account show -o json   # Display an account, in json

% madonctl stream               # Stream home timeline and notifications
% madonctl stream public        # Stream federated timeline
% madonctl stream :mastodon     # Stream a hashtag-based timeline
% madonctl stream local -o json # Stream local timeline and output to JSON
You can also use Go (Golang) templates:
% madonctl accounts --account-id 1 followers --template '{{.acct}}{{"\n"}}'

Shell completion

If you want shell completion, you can generate scripts with the madonctl completion bash (or zsh) command.
Then, just source the script in your shell.
I have this line in my .zshrc:
source <(madonctl completion zsh)


The output can be set to json, yaml or to a Go template for all commands.
If you are familiar with Kubernetes' kubectl, it is very similar.

For example, you can display your user token with:
madonctl config whoami --template '{{.access_token}}'
or the application ID with:
madonctl config dump --template '{{.ID}}'

All the users that have favorited a status:
madonctl status --status-id 101194 favourited-by --template '{{.username}}{{"\n"}}'

Status of the implementation

This list is out-of-date (it was written for the first versions of madonctl), you should refer to the manpages or the Github README for accurate information, but this can give you an idea of the commands.
* Help

  - madonctl
  - madonctl command --help

* Configuration

  - madonctl completion bash|zsh
  - madonctl config dump
  - madonctl config whoami

* Standard API

  - madonctl account [--account-id ACCOUNTID] show
  - madonctl account [--account-id ACCOUNTID] followers
  - madonctl account [--account-id ACCOUNTID] following
  - madonctl account [--account-id ACCOUNTID] statuses
  - madonctl account --account-id ACCOUNTID follow
  - madonctl account --account-id ACCOUNTID follow --unset
  - madonctl account --account-id ACCOUNTID block
  - madonctl account --account-id ACCOUNTID block --unset
  - madonctl account --account-id ACCOUNTID mute
  - madonctl account --account-id ACCOUNTID mute --unset
  - madonctl account relationships --account-ids ID...
  - madonctl account search STRING --limit N  (--limit not implemented)
  - madonctl account update --display-name NAME --note NOTE --avatar AVATARIMG --header HEADERIMG
  - madonctl account blocks
  - madonctl account favourites
  - madonctl account follow_requests --list
  - madonctl account follow_requests --accept --account-id ACCOUNTID
  - madonctl account follow_requests --reject --account-id ACCOUNTID
  - madonctl account follow --remote UID
  - madonctl instance
  - madonctl media|upload --file FILENAME
  - madonctl account mutes
  - madonctl account notifications --list
  - madonctl account notifications --id NOTIFID
  - madonctl account notifications --clear
  - madonctl account reports --list
  - madonctl account reports --account-id ACCOUNTID --status-ids ID... --comment TEXT
  - madonctl search [--resolve] STRING
  - madonctl status --status-id STATUSID show
  - madonctl status --status-id STATUSID context
  - madonctl status --status-id STATUSID card
  - madonctl status --status-id STATUSID reblogged-by
  - madonctl status --status-id STATUSID favourited-by
  - madonctl status --status-id STATUSID delete
  - madonctl status --status-id STATUSID boost|reblog
  - madonctl status --status-id STATUSID boost|reblog --unset
  - madonctl status --status-id STATUSID favourite
  - madonctl status --status-id STATUSID favourite --unset
  - madonctl toot|post [--visibility VISIBILITY] [--sensitive] [--spoiler SPOILERTEXT] [--in-reply-to STATUSID] [[--file mediafile]|[--media-ids MIDS...]] TEXT
  - madonctl timeline [home]
  - madonctl timeline public [--local]
  - madonctl timeline :TAG|#TAG

* Streaming API

  - madonctl stream [user]
  - madonctl stream public|local
  - madonctl stream :tag|#tag

Repository mirrors