Mastodon
  • What is Mastodon?
  • Using Mastodon
    • Signing up for an account
    • Setting up your profile
    • Posting toots
    • Using the network features
    • Dealing with unwanted content
    • Promoting yourself and others
    • Set your preferences
    • More settings
    • Using Mastodon externally
    • Moving or leaving accounts
    • Running your own server
  • Running Mastodon
    • Preparing your machine
    • Installing from source
    • Configuring your environment
    • Installing optional features
      • Full-text search
      • Hidden services
      • Single Sign On
    • Setting up your new instance
    • Using the admin CLI
    • Upgrading to a new release
    • Backing up your server
    • Migrating to a new machine
    • Scaling up your server
    • Moderation actions
    • Troubleshooting errors
      • Database index corruption
  • Developing Mastodon apps
    • Getting started with the API
    • Playing with public data
    • Obtaining client app access
    • Logging in with an account
    • Guidelines and best practices
    • Libraries and implementations
  • Contributing to Mastodon
    • Technical overview
    • Setting up a dev environment
    • Code structure
    • Routes
    • Bug bounties and responsible disclosure
  • Spec compliance
    • ActivityPub
    • WebFinger
    • Security
    • Microformats
    • OAuth
    • Bearcaps
  • REST API
    • OAuth Scopes
    • Rate limits
  • API Methods
    • apps
      • oauth
    • accounts
      • bookmarks
      • favourites
      • mutes
      • blocks
      • domain_blocks
      • filters
      • reports
      • follow_requests
      • endorsements
      • featured_tags
      • preferences
      • suggestions
    • statuses
      • media
      • polls
      • scheduled_statuses
    • timelines
      • conversations
      • lists
      • markers
      • streaming
    • notifications
      • push
    • search
    • instance
      • trends
      • directory
      • custom_emojis
    • admin
    • announcements
    • proofs
    • oembed
  • API Entities
    • Account
    • Activity
    • Admin::Account
    • Admin::Report
    • Announcement
    • AnnouncementReaction
    • Application
    • Attachment
    • Card
    • Context
    • Conversation
    • Emoji
    • Error
    • FeaturedTag
    • Field
    • Filter
    • History
    • IdentityProof
    • Instance
    • List
    • Marker
    • Mention
    • Notification
    • Poll
    • Preferences
    • PushSubscription
    • Relationship
    • Report
    • Results
    • ScheduledStatus
    • Source
    • Status
    • Tag
    • Token

Using the admin CLI

tootctl commands that can be run from the CLI.

    • Base CLI
    • Accounts CLI
    • Cache CLI
    • Domains CLI
    • Email domain blocks CLI
    • Emoji CLI
    • Feeds CLI
    • Maintenance CLI
    • Media CLI
    • Preview Cards CLI
    • Search CLI
    • Settings CLI
    • Statuses CLI
    • Upgrade CLI

The command-line interface of Mastodon is an executable file called tootctl residing in the bin directory within the Mastodon root directory. You must specify which environment you intend to use whenever you execute it by specifying the RAILS_ENV environment variable. Unless you are a developer working on a local machine, you need to use RAILS_ENV=production. If you are sure that you will never need another environment (for development, testing, or staging), you can add it to your .bashrc file for convenience, e.g.:

echo "export RAILS_ENV=production" >> ~/.bashrc

If so, you won’t need to specify it each time inline. Otherwise, calls to tootctl will usually go like this, assuming that the Mastodon code is checked out in /home/mastodon/live:

cd /home/mastodon/live
RAILS_ENV=production bin/tootctl help

Base CLI

lib/cli.rb

tootctl self-destruct

Erase this server from the federation by broadcasting account Delete activities to all known other servers. This allows a “clean exit” from running a Mastodon server, as it leaves next to no cache behind on other servers. This command is always interactive and requires confirmation twice.

No local data is actually deleted, because emptying the database or deleting the entire VPS is faster. If you run this command then continue to operate the instance anyway, then there will be a state mismatch that might lead to glitches and issues with federation.

Make sure you know exactly what you are doing before running this command. This operation is NOT reversible, and it can take a long time. The server will be in a BROKEN STATE after this command finishes. A running Sidekiq process is required, so do not shut down the server until the queues are fully cleared.

Version history:
2.8.0 - added

OptionDescription
--dry-runPrint expected results only, without performing any actions.

tootctl --version

Show the version of the currently running Mastodon instance.

Version history:
2.7.0 - added

Accounts CLI

lib/mastodon/accounts_cli.rb

tootctl accounts rotate

Generate and broadcast new RSA keys, as part of security maintenance.

Version history:
2.5.0 - added

OptionDescription
USERNAMELocal username for an account.
--allCan be provided instead of USERNAME to rotate keys for all local accounts.

tootctl accounts create

Create a new user account with given USERNAME and provided –email.

Version history:
2.6.0 - added

OptionDescription
USERNAMELocal username for the new account. Required.
--email EMAILEmail address to be attached to the user. Required.
--confirmedSkip sending the confirmation email and activate the account immediately.
--role ROLEDefine the new account as a user, moderator, or admin. Defaults to user.
--reattachReuse an old USERNAME after its account has been deleted.
--forceForcefully delete any existing account with this USERNAME and reattach the new account in place of the (just-deleted) account.

tootctl accounts modify

Modify a user account's role, email, active status, approval mode, or 2FA requirement.

Version history:
2.6.0 - added
3.1.2 - added --reset-password

OptionDescription
USERNAMELocal username for the account. Required.
--role ROLEDefine the account as a user, moderator, or admin.
--email EMAILUpdate the user's email address to EMAIL.
--confirmSkip confirmation email, when used with –email.
--disableLock USERNAME out of their account.
--enableUnlock USERNAME's account if it is currently disabled.
--approveApprove the account, if you are/were in approval mode.
--disable-2faRemove additional factors and allow login with password.
--reset-passwordResets the password of the given account.

tootctl accounts delete

Delete a user account with given USERNAME.

Version history:
2.6.0 - added

OptionDescription
USERNAMELocal username for the account. Required.

tootctl accounts backup

Request a backup for a user account with given USERNAME. The backup will be created in Sidekiq asynchronously, and the user will receive an email with a link to it once it's done.

Version history:
2.6.0 - added

OptionDescription
USERNAMELocal username for the account. Required.

tootctl accounts cull

Remove remote accounts that no longer exist. Queries every single remote account in the database to determine if it still exists on the origin server, and if it doesn't, then remove it from the database. Accounts that have had confirmed activity within the last week are excluded from the checks, in case the server is just down.

Version history:
2.6.0 - added
2.8.0 - add --dry-run

OptionDescription
--concurrency NThe number of workers to use for this task. Defaults to N=5.
--dry-runPrint expected results only, without performing any actions.

tootctl accounts refresh

Refetch remote user data and files for one or multiple accounts.

Version history:
2.6.0 - added

OptionDescription
USERNAME[email protected] for the remote account.
--allCan be provided instead of USERNAME to refresh all remote accounts.
--domain DOMAINCan be provided instead of USERNAME. Operate only on remote accounts from this DOMAIN.
--concurrency NThe number of workers to use for this task. Defaults to N=5.
--verbosePrint additional information while task is processing.
--dry-runPrint expected results only, without performing any actions.

tootctl accounts merge

Merge two remote accounts into one. This is primarily meant to fix duplicates caused by other servers changing their domain. By default, this only works if the public key is the same, but this can be overridden.

Version history:
3.3.0 - added

OptionDescription
FROM[email protected] for the remote account to be removed.
TO[email protected] for the remote account to be kept.
--forceOverride the public key check.

tootctl accounts follow

Force all local accounts to follow a local account specified by username.

Version history:
2.7.0 - added
3.0.0 - now uses USERNAME instead of ACCT

OptionDescription
USERNAMELocal username
--concurrency NThe number of workers to use for this task. Defaults to N=5.
--verbosePrint additional information while task is processing.

tootctl accounts unfollow

Force all local accounts to unfollow an account specified by their address.

Version history:
2.7.0 - added

OptionDescription
ACCT[email protected] address
--concurrency NThe number of workers to use for this task. Defaults to N=5.
--verbosePrint additional information while task is processing.

tootctl accounts reset-relationships

Reset all follow and/or follower relationships for a local account.

Version history:
2.8.0 - added

OptionDescription
USERNAMELocal username
--followsForce USERNAME to unfollow everyone, then re-follow them.
--followersRemove all of USERNAME's followers.

tootctl accounts approve

Approve new registrations when instance is in approval mode.

Version history:
2.8.0 - added

OptionDescription
USERNAMEApprove the pending account with this username.
--number NApprove the N most recent registrations.
--allApprove all pending registrations.

Cache CLI

lib/mastodon/cache_cli.rb

tootctl cache clear

Clear out the cache storage.

Version history:
2.8.1 - added

tootctl cache recount

Update hard-cached counters of TYPE by counting referenced records from scratch. It may take a very long time to finish, depending on the size of the database. Accounts will have their follower, following, and status counts refreshed. Statuses will have their reply, boost, and favourite counts refreshed.

Version history:
3.0.0 - added

OptionDescription
TYPEEither accounts or statuses
--concurrency NThe number of workers to use for this task. Defaults to N=5.
--verbosePrint additional information while task is processing.

Domains CLI

lib/mastodon/domains_cli.rb

tootctl domains purge

Remove all accounts from a given DOMAIN without leaving behind any records. Unlike a suspension, if the DOMAIN still exists in the wild, it means the accounts could return if they are resolved again.

Version history:
2.6.0 - added
2.8.0 - add --whitelist-mode
2.9.0 - remove custom emoji as well
3.0.0 - accept multiple domains
3.2.0 - rename --whitelist-mode to --limited-federation-mode

OptionDescription
DOMAIN[...]Domains to purge, separated by space.
--limited-federation-modeCan be provided instead of DOMAIN. Instead of purging from a single domain, all accounts from domains that are not allow-listed will be removed from the database. Use this after enabling limited federation mode and defining your allow-list.
--concurrency NThe number of workers to use for this task. Defaults to 5.
--verbosePrint additional information while task is processing.
--dry-runPrint expected results only, without performing any actions.

tootctl domains crawl

Crawl the known fediverse by using Mastodon REST API endpoints that expose all known peers, and collect statistics from those peers, as long as those peers support those API endpoints. When no START is given, the command uses the server's own database of known peers to seed the crawl. Returns total servers, total registered users, total active users in the last week, and total users joined in the last week.

Version history:
2.7.0 - added
3.0.0 - add --exclude-suspended

OptionDescription
STARTOptionally start from a different domain name.
--concurrency NThe number of workers to use for this task. Defaults to 50.
--format FORMATControl how results are returned. summary will print a summary. domains will return a newline-delimited list of all discovered peers. json will dump aggregated raw data. Defaults to summary.
--exclude-suspendedDo not include instances that you have suspended in the output. Also includes any subdomains.

Email domain blocks CLI

lib/mastodon/email_domain_blocks_cli.rb

tootctl email-domain-blocks list

List all currently blocked email domains.

Version history:
3.2.0 - added

tootctl email-domain-blocks add

Add entries to the e-mail domain blocklist.

Version history:
3.2.0 - added

OptionDescription
DOMAIN[...]E-mail domains to block, separated by space.
--with-dns-recordsIf provided, will also lookup A, AAAA, and MX records and block them as well.

tootctl email-domain-blocks remove

Remove entries from the e-mail domain blocklist.

Version history:
3.2.0 - added

OptionDescription
DOMAIN[...]E-mail domains to unblock, separated by space.

Emoji CLI

lib/mastodon/emoji_cli.rb

tootctl emoji export

Exports custom emoji to export.tar.gz at PATH.

Version history:
3.1.4 - added

OptionDescription
PATHPath to create a .tar.gz archive containing pictures.
--overwriteOverwrite the existing archive.
--category CATEGORYExport only the specified CATEGORY. If not provided, will export all emoji.

tootctl emoji import

Imports custom emoji from a .tar.gz archive at a given path. The archive should contain PNG or GIF files no larger than 50KB, and the shortcode will be set equal to the filename minus the extension, with optional prefixes and/or suffixes.

Version history:
2.5.0 - added

OptionDescription
PATHPath to a .tar.gz archive containing pictures.
--prefix PREFIXAdd PREFIX to the beginning of generated shortcodes.
--suffix SUFFIXAdd SUFFIX to the end of generated shortcodes.
--overwriteInstead of skipping existing emoji, replace them with any discovered emoji with the same shortcode.
--unlistedProcessed emoji will not be shown in the emoji picker, but will be usable only by their direct shortcode.
--category CATEGORYGroup the processed emoji under CATEGORY in the picker.

tootctl emoji purge

Remove all custom emoji.

Version history:
2.8.0 - added
3.1.0 - add --remote-only

OptionDescription
--remote-onlyIf provided, remove only from remote domains.

Feeds CLI

lib/mastodon/feeds_cli.rb

tootctl feeds build

Build home and list feeds for one or all users. Feeds will be built from the database and cached in-memory with Redis. Mastodon manages home feeds for active users automatically.

Version history:
2.6.0 - added

OptionDescription
USERNAMELocal username whose feeds will be regenerated.
--allCan be provided instead of USERNAME to refresh all local accounts’ feeds.
--concurrency NThe number of workers to use for this task. Defaults to N=5.
--verbosePrint additional information while task is processing.
--dry-runPrint expected results only, without performing any actions.

tootctl feeds clear

Remove all home and list feeds from Redis.

Version history:
2.6.0 - added

Maintenance CLI

lib/mastodon/maintenance_cli.rb

tootctl maintenance fix-duplicates

Fix corrupted database indexes that may have been caused due to changing collation rules. Deletes or merges duplicate accounts, statuses, emojis, etc. Mastodon has to be stopped to run this task, which will take a long time and may be destructive. This is useful if your database indexes are corrupted because of issues such as https://wiki.postgresql.org/wiki/Locale_data_changes.

Media CLI

lib/mastodon/media_cli.rb

tootctl media remove

Remove locally cached copies of media attachments from other servers.

Version history:
2.5.0 - added
2.6.2 - show freed disk space

OptionDescription
--daysHow old media attachments have to be before they are removed. Defaults to 7.
--concurrency NThe number of workers to use for this task. Defaults to 5.
--verbosePrint additional information while task is processing.
--dry-runPrint expected results only, without performing any actions.

tootctl media remove-orphans

Scans for files that do not belong to existing media attachments, and remove them. Please mind that some storage providers charge for the necessary API requests to list objects. Also, this operation requires iterating over every single file individually, so it will be slow.

Version history:
3.1.0 - added
3.1.3 - added --prefix
3.3.0 - added --fix-permissions

OptionDescription
--start-afterThe Paperclip attachment key where the loop will start. Use this option if the command was interrupted before.
--dry-runPrint expected results only, without performing any actions.
--prefixTraverse only a specific prefix of files in the system.
--fix-permissionsSets S3 ACL to be default according to environment variables.

tootctl media refresh

Refetch remote media attachments from other servers. You must specify the source of media attachments with either –status, –account, or –domain. If an attachment already exists in the database, it will not be overwritten unless you use –force.

Version history:
3.0.0 - added
3.0.1 - add --force and skip already downloaded attachments by default

OptionDescription
--account ACCTString [email protected] handle of the account
--domain DOMAINFQDN string
--status IDLocal numeric ID of the status in the database.
--concurrency NThe number of workers to use for this task. Defaults to 5.
--verbosePrint additional information while task is processing.
--dry-runPrint expected results only, without performing any actions.
--forceForce redownload the remote resource and overwrite the local attachment.

tootctl media usage

Calculate disk space consumed by Mastodon.

Version history: 3.0.1 - added

tootctl media lookup

Prompts for a media URL, then looks up where the media is displayed.

Version history:
3.1.0 - added

Preview Cards CLI

lib/mastodon/preview_cards_cli.rb

tootctl preview_cards remove

Remove local thumbnails for preview cards.

Version history:
3.0.0 - added

OptionDescription
--daysHow old media attachments have to be before they are removed. Defaults to 180. (NOTE: it is not recommended to delete preview cards within the last 14 days, because preview cards will not be refetched unless the link is reposted after 2 weeks from last time.)
--concurrency NThe number of workers to use for this task. Defaults to 5.
--verbosePrint additional information while task is processing.
--dry-runPrint expected results only, without performing any actions.
--linkOnly delete link-type preview cards; leave video and photo cards untouched.

Search CLI

lib/mastodon/search_cli.rb

tootctl search deploy

Create or update an ElasticSearch index and populate it. If ElasticSearch is empty, this command will create the necessary indices and then import data from the database into those indices. This command will also upgrade indices if the underlying schema has been changed since the last run.

Version history: 2.8.0 - added
3.0.0 - add --processes for parallelization 3.3.0 - options changed

OptionDescription
--concurrency NParallelize execution of the command on multiple threads. Defaults to N=2.
--only INDEXSpecify an index name [accounts, tags, statuses] to create or update only that index.

Settings CLI

lib/mastodon/settings_cli.rb

tootctl settings registrations open

Opens registrations.

Version history:
2.6.0 - added

tootctl settings registrations close

Closes registrations.

Version history:
2.6.0 - added

Statuses CLI

lib/mastodon/statuses_cli.rb

tootctl statuses remove

Remove unreferenced statuses from the database, such as statuses that came from relays or from users who are no longer followed by any local accounts, and have not been replied to or otherwise interacted with.

This is a computationally heavy procedure that creates extra database indices before commencing, and removes them afterward.

Version history:
2.8.0 - added
3.1.3 - added --skip-media-remove

OptionDescription
--daysHow old statuses have to be before they are removed. Defaults to 90.
--skip-media-removeSkips removing the media, in case S3 errors out. Defaults to false.

Upgrade CLI

lib/mastodon/upgrade_cli.rb

tootctl upgrade storage-schema

Upgrade the storage schema to store all non-local media resources in a top-level cache directory. WARNING: This is optional, and only for deployments made before v3.1.4. This command can incur massive object storage costs due to moving potentially terabytes of data.

Version history:
3.1.4 - added

OptionDescription
--verbosePrint additional information while task is processing.
--dry-runPrint expected results only, without performing any actions.

Last updated February 15, 2021 · Improve this page
Also available in: 简体中文