About madonctl

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

The API should have a 100% coverage as of Mastodon 1.2.2.

Documentation

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

Download

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.

Configuration

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.

Note that 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 a configuration file.)

Examples

% 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 accounts 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 accounts follow --remote Gargron@mastodon.social

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

% madonctl stream               # Stream home timeline and notifications
% madonctl stream public        # Stream federated 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)

Output

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

* Help

  - madonctl
  - madonctl command --help

* Configuration

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

* Standard API

  - madonctl accounts [--account-id ACCOUNTID] show
  - madonctl accounts --account-id ACCOUNTID followers
  - madonctl accounts --account-id ACCOUNTID following
  - madonctl accounts --account-id ACCOUNTID statuses
  - madonctl accounts --account-id ACCOUNTID follow
  - madonctl accounts --account-id ACCOUNTID follow --unset
  - madonctl accounts --account-id ACCOUNTID block
  - madonctl accounts --account-id ACCOUNTID block --unset
  - madonctl accounts --account-id ACCOUNTID mute
  - madonctl accounts --account-id ACCOUNTID mute --unset
  - madonctl accounts relationships --account-ids ID...
  - madonctl accounts search STRING --limit N  (--limit not implemented)
  - madonctl accounts update --display-name NAME --note NOTE --avatar AVATARIMG --header HEADERIMG
  - madonctl accounts blocks
  - madonctl accounts favourites
  - madonctl accounts follow_requests --list
  - madonctl accounts follow_requests --accept --account-id ACCOUNTID
  - madonctl accounts follow_requests --reject --account-id ACCOUNTID
  - madonctl accounts follow --remote UID
  - madonctl instance
  - madonctl media|upload --file FILENAME
  - madonctl accounts mutes
  - madonctl accounts notifications --list
  - madonctl accounts notifications --id NOTIFID
  - madonctl accounts notifications --clear
  - madonctl accounts reports --list
  - madonctl accounts 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

* Stream API

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