wikicmd

wikicmd is a command-line utility for working with MediaWiki websites, such as the Wikipedia.

$ wikicmd edit 'Some page'
# Your favorite editor will then open up and you can edit the 'Some page' article.

Check the Command Reference section on the menu to know all the possible operations.

Getting Started

For installation instructions, see Installation. If you just want to quickly download the latest version:

License

wikicmd is licensed under MIT. See License here for more details.

Installation

Download it

This is the easiest installation method.

$ wget https://github.com/dhuan/wikicmd/releases/download/v0.2.1/wikicmd_v0.2.1_linux-386.zip
$ unzip wikicmd_v0.2.1_linux-386.zip

If you're using MacOS, you'll need to replace the download link above with the one for your platform. Check the releases page to see all supported platforms and download the one that matches your system.

A wikicmd binary should then be available to you at your current directory. You can just use it:

$ ./wikicmd

Optionally, you may move it to your user's programs folder in order to make it executable without specifying the program's path:

$ mv ./wikicmd ~/bin/.
$ wikicmd

Installing from source

Make sure that your system meets the following requirements before proceeding:

$ git clone https://github.com/dhuan/wikicmd.git
$ cd wikicmd
$ make build

You should then have an executable named wikicmd located in the bin folder of the repository, which you can execute:

$ ./bin/wikicmd

Configuring

wikicmd looks for ~/.wikicmd.json in order to read your configuration. You can either create this file by hand, or you can run the config command where a command-line wizard will help you to accomplish the same.

$ wikicmd config
Wiki address: (https://en.wikipedia.org/w)
Login: myuser
Password: mypassword
Next, a configuration file will be created for you and saved as /home/myuser/.wikicmd.json

Is this OK? (yes):    
Done!

If you want your configuration file to be located in a place other than ~/.wikicmd.json, you can set the WIKICMD_CONFIG shell environment variable, pointing to a place of your preference.

Configuration Structure

A configuration file is formatted as follows:

{
  "wikis": [
    {
      "id": "my_wiki",
      "address": "https://en.wikipedia.org/w",
      "user": "myuser",
      "password": "mypassword"
    }
  ]
}

The wikis field takes a list of "Wiki Configuration Objects". In the example above, we have only one Wiki, my_wiki, that we want to manage with wikicmd. If you want to configure wikicmd to be able to use multiple wikis, make sure to read about the switch command.

Configuration Parameters

Wiki Object

id

An ID to identify a Wiki with.

address

A Wiki URL. For example https://en.wikipedia.org/w.

user

A username that you can login with.

password

Your password.

importExtensions (optional)

A list of file extensions that can be be imported.

MediaWiki by default allows only a set of file types to be uploaded. However there are extensions that enhance MediaWiki to allow other kinds of files. If you customised your wiki to enable uploading other types of files, you can use this configuration parameter to enable wikicmd to import these files.

"importExtensions": [
  "mp4",
  "avi",
  "wmv"
]

Root Level Configuration

The following configuration parameters are not related to any specific Wiki instance.

editor (optional)

Sets the text-editing program for editing Wiki Pages. Defaults to vim if not set. The EDITOR shell environment variable can also be used to overwrite this option.

default (optional)

The wiki that you're currently working with. This parameter is manipulated by the switch command.

Get your Wiki Credentials

wikicmd is meant to be used with MediaWiki's Bot Passwords. Getting your Bot Password is an easy process once you have your user account for Wikipedia or any MediaWiki website. This guide will show you how to do it.

This guide links to Wikipedia but you can follow these steps in any MediaWiki instance.

1-) Get your account

Signup to Wikipedia here if you don't have an account yet. Then login with your account in Wikipedia.

2-) Setup your Bot Password

Click here to go to the Bot Password page.

Under Bot Name, type a bot name of your preference. You'll use it later when configuring wikicmd. Click Create.

Next, you'll be asked which privileges to assign to your new Bot Password. The following privileges are relevant to wikicmd - you will want to check them:

Import revisions
Edit existing pages
Edit protected pages
Create, edit, and move pages
Upload new files
Upload, replace, and move files
Delete pages

Click Create. MediaWiki creates a random password for you, which is shown immediately after you've created your Bot Password. Make sure not to lose the information in this page, as you'll be using it in the next step configuring wikicmd.

3-) Configure wikicmd with your new Bot Password

Supposing that your Wikipedia's Username is JohnDoe and your Bot Password is named mybot, and the randomly generated password is 123456789, your wikicmd configuration should then be edited as such:

{
  "wikis": [
    {
      "id": "my_wiki",
      "address": "https://en.wikipedia.org/w",
      "user": "JohnDoe@mybot",
      "password": "123456789"
    }
  ]
}

Having followed these steps, wikicmd should be set and ready to be used. In case of issues, you can report bugs in this link.

Troubleshooting

If you're facing issues, it may help to use the verbose flag -v. It will output for you a bunch of useful log messages, including each HTTP request that's being sent, and their responses.

$ wikicmd -v edit 'Some page'

F.A.Q

A common mistake is trying to setup wikicmd with your actual login and password information, when you should instead setup a Bot Password for your account. Check this guide for more details.

In case you're still facing this issue even after making sure that your Bot Password is set correctly, maybe it'd be better to report the issue.

I don't like the editor that opens up when I use wikicmd's `edit`. How do I use editor X?

$ export EDITOR=vscode
$ wikicmd edit 'Some page'

Compatibility

The following is a list of versions of MediaWiki with which wikicmd has been tested and is known to work.

1.37.2
1.37.1
1.37.0

config

Opens your configuration file for editing, located at ~/.wikicmd.json, if it exists. Otherwise creates a new configuration file for you.

$ wikicmd config

Options

--new

Overwrites your existing configuration with a new one, taking you through the "New configuration wizard" before.

Edit

Opens a Wiki Page for editing, given a page name. If there's no page with the given name, a new one will be created once you've saved and exited the editor.

$ wikicmd edit 'Some wiki page'

Options

--message | -m: The edit summary. If this option is not set, you'll be manually prompted to set an Edit Summary after you've saved the page's changes.

Export

Exports Wiki content to a given folder in your computer. The given folder must exist.

$ wikicmd export /path/to/export/to

Options

--type | -t: Content type that you want to export. The following types can be given:

all
page
image

Defaults to all.

Import

Imports pages or images.

$ wikicmd import /path/to/some/files/*.jpg
$ wikicmd import /path/to/some/files/*.wikitext

What files can be imported

Wiki pages: Text files with the .wikitext or .txt. extension.

Images: Images with the following extensions can be imported: .jpg, .jpeg, .png.

Options

--message | -m: The edit summary. If set, the imported content will be saved with the given summary message.

switch

Sets the current Wiki that you're working with, given a Wiki ID.

$ wikicmd switch my_wiki

Your wikicmd configuration file can contain multiple Wiki Configuration Objects.

{
  "wikis": [
    {
      "id": "my_wiki"
      ...
    },
    {
      "id": "another_wiki"
      ...
    }
  ]
}

Given the configuration structure above, we could switch to either my_wiki or another_wiki.

If you're using wikicmd to work with a single Wiki only, you won't be using this command.