madonctl

Golang command line interface for the Mastodon API

madonctl is a Go CLI tool to use the Mastodon REST API.

It is built on top of madon, my Golang implementation of the API.

Installation

Download

Check the Release page for some pre-built binaries.

More pre-built binaries might be available from the Homepage (development version and builds for a few other platforms).

From source

madonctl uses Go modules (dependencies have been vendored for convenience).

You can install the latest madonctl release with the usual Go command:

go install github.com/McKael/madonctl/v3@latest

Or if you want the current master branch:

go install github.com/McKael/madonctl/v3@master

Alternatively:

git clone https://github.com/McKael/madonctl
cd madonctl
go build    # (or go install)

and you should be able to use madonctl.

Usage

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.)

If you don't want to use the password or if you have enabled Two-factor authentication, you can also use OAuth2 with the oauth2 command:

madonctl -i mastodon.social oauth2 > madonctl.yaml

For details on the configuration, please check the configuration page.

Usage

The complete list of commands is available in the online help (madonctl help, madonctl command --help...) or in the manpages.

Examples

This is a non-exhaustive list of commands, showing how madonctl works.

To post a simple "toot":

% madonctl toot "Hello, World"

You can change the toot visibility, add a Content Warning (a.k.a. spoiler) or send a media file:

% 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

Note: The default toot visibility can be set in the configuration file with the default_visibility setting or with the environment variable (example export MADONCTL_DEFAULT_VISIBILITY=unlisted).

Send (text) file content as new message:

% madonctl toot --text-file message.txt

... or read message from standard input:

% echo "Hello from #madonctl" | madonctl toot --stdin

Reply to a message:

% madonctl toot --in-reply-to 1234 --visibility direct "@user1 @user2 response"
% madonctl toot --in-reply-to 1234 --add-mentions "response"

The flag --add-mentions automatically adds mentions based on the toot you're replying to.

Some account-related commands:

% madonctl accounts blocked                       # List blocked accounts
% madonctl accounts muted                         # List muted accounts

% madonctl account notifications --list --all    # List really all notifications
% madonctl account notifications --list --clear  # List and clear notifications
% madonctl account notifications --notification-id 1234 # Display notification
% madonctl account notifications --dismiss --notification-id 1234

Note: By default, madonctl will send a single query. If you want all available results you should use the --all flag. If you use a --limit value, madonctl might send several queries until the number of results reaches this value.

Update your account information:

% madonctl account update --display-name "John"  # Update display name
% madonctl account update --note "Newcomer"      # Update user note (bio)
% madonctl account update --note ""              # Clear note
% madonctl account update --avatar me.png        # Update avatar

% madonctl account update --bot               # Advertise account as automated
% madonctl account update --default-sensitive # Set medias sensitive by default
% madonctl account update --default-language fra    # Set default toot language
% madonctl account update --default-privacy private # Set default toot privacy

See your own posts:

% madonctl account statuses                      # See last posts
% madonctl account statuses --all                # See all statuses

Display accounts you're following or your followers:

% madonctl accounts following                     # See last following
% madonctl accounts following --all               # See all followed accounts
% madonctl accounts followers --limit 30          # Last 30 followers

Add/remove a favourite, boost a status...

% madonctl status --status-id 416671 favourite    # Fave a status
% madonctl status --status-id 416671 boost        # Boost (reblog) a status

% madonctl status --status-id 416671 unboost       # Cancel a boost

Pin/unpin a status...

% madonctl status --status-id 533769 pin          # Pin a status
% madonctl status --status-id 533769 unpin        # Unpin a status

Pin/unpin an account (i.e., account endorsement)...

% madonctl status --account-id 1234 pin           # Pin (endorse) an account
% madonctl status --account-id 1234 unpin         # Unpin an account

% madonctl status pin @[email protected]

Search for an account (only accounts known to your instance):

% madonctl accounts search gargron

Follow an account with known ID:

% madonctl account follow --account-id 1234

Follow a remote account:

% madonctl account follow --remote [email protected]

madonctl 2.3.0+ is able to recognize the kind of argument to specify and to use the relevant API calls, so the previous commands could be written as:

% madonctl account follow 1234
% madonctl account follow [email protected]
% madonctl account follow https://mastodon.social/@Gargron

Note: If you know the numeric account ID, you should use it to save extra API calls.

Search for accounts, statuses or hashtags:

% madonctl search gargron
% madonctl search mastodon

When the account ID is unknown, --user-id can be useful.
You can specify the (instance-specific) account ID number (--account-id) or the user ID (--user-id). In the later case, madonctl will search for the user so it must match exactly the ID known to your instance (without the @domain suffix if the user is on the same instance). The --user-id flag can also contain an HTTP account URL.

% madonctl account --user-id [email protected] -l5 statuses # Last 5 statuses
% madonctl account --user-id https://mastodon.social/@Gargron -l5 statuses # Same

With madonctl 2.3.0+, you can use the shorter forms:

% madonctl account statuses -l5 [email protected]
% madonctl account statuses -l5 https://mastodon.social/@Gargron
% madonctl account statuses -l5 1   # (account ID)

Please note that the form "[email protected]" will only work if this account is known by the instance. If it is unknown, the https link should work (and the Mastodon server will learn about the account).

Read timelines:

% madonctl timeline                 # Display home timeline
% madonctl timeline home            # (same as previous command)
% madonctl timeline public          # Display federated timeline
% madonctl timeline public --local  # Display public local timeline
% madonctl timeline direct          # Display timeline of direct messages

% madonctl timeline --limit 3       # Display 3 latest home timeline messages

Use the streaming API and fetch timelines and notifications:

% madonctl stream                   # Stream home timeline and notifications
% madonctl stream local             # Stream local timeline
% madonctl stream public            # Stream federated timeline
% madonctl stream direct            # Stream direct messages

You can also use hashtag streams:

% madonctl stream :mastodon         # Stream for hastag 'mastodon'
% madonctl stream :madonctl,golang  # Stream for several hashtags

Please note that madonctl will use one socket per stream, so the number of concurrent hashtags is currently limited to 4 for "politeness".

It is also possible to send every stream event (notification or status) to an external command. You can can even combine it with a customized theme. The contents will be sent to the standard input of this command:

madonctl stream --command gateway.sh --theme gateway

(Almost) All commands have a customizable output:

% 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 local -o json     # Stream local timeline and output to JSON

You can also use Go (Golang) templates:

% madonctl account --account-id 1 followers --template '{{.acct}}{{"\n"}}'

You can write and use themes as well:

madonctl --theme=ansi timeline

There are many more commands, you can find them in the online help or the manpage.

Shell completion

If you want shell completion, you can generate scripts with the following command:
madonctl completion bash (or zsh)

Then, just source the script in your shell.

For example, I have this line in my .zshrc:

source <(madonctl completion zsh)

Commands 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 given status:
madonctl status --status-id 101194 favourited-by --template '{{.username}}{{"\n"}}'

Sets of templates can be grouped as themes.

For more complex templates, one can use the --template-file option.
See the themes & templates folder.

References

• madonctl manpages
• madon, the Go library for Mastodon API
• Mastodon API documentation
• Mastodon repository