madonctl

README

madonctl

Golang command line interface for the Mastodon API

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

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

Installation

From source

To install the application from source (you need to have Go >= 1.7), just type:

go get -u github.com/McKael/madonctl

and you should be able to run madonctl.

For upgrades, don't forget the -u option to ensure the dependencies (especially madon) are updated as well.

Travis automated testing is run for Go versions 1.7 and 1.8.

Download

Check the Release page for some pre-built binaries.

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

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

Note that every variable from the configration file can also be set with an environment variable (e.g. export MADONCTL_INSTANCE='https://mamot.fr').

Usage

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

Examples

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

Some account-related commands:

% madonctl accounts blocked                       # List blocked accounts
% madonctl accounts muted                         # List muted accounts
% madonctl accounts notifications --list --all    # List really all notifications
% madonctl accounts notifications --list --clear  # List and clear notifications
% madonctl accounts notifications --notification-id 1234 # Display notification
% madonctl accounts notifications --dismiss --notification-id 1234 # Mastodon 1.3+

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 accounts update --display-name "John"  # Update display name
% madonctl accounts update --note "Newcomer"      # Update user note (bio)
% madonctl accounts update --note ""              # Clear note
% madonctl accounts update --avatar me.png        # Update avatar

See your own posts:

% madonctl accounts statuses                      # See last posts
% madonctl accounts statuses --all                # See all statuses
% madonctl accounts --user-id Gargron@mastodon.social -l5 # Last 5 statuses

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). With madonctl v0.6.1+, the --user-id flag can also contain an HTTP account URL.

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 a status

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

% madonctl accounts search gargron

Follow an account with known ID:

% madonctl accounts follow --account-id 1234

Follow a remote account:

% madonctl accounts follow --remote Gargron@mastodon.social

Read timelines:

% madonctl timeline                 # Display home timeline
% madonctl timeline public          # Display federated timeline
% madonctl timeline public --local  # Display public local timeline

% 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

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

(Almost) All commands have a customisable output:

% 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 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"}}'

Number of users on current instance (statistics from instances.mastodon.xyz API):

madonctl instance --stats --template '{{printf "%v\n" .users}}'

You can write and use themes as well (madonctl 0.6+):

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"}}'

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

References

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