Skip to main content

A CLI for the Read The Docs v3 API

Project description

A work in progress.

Made to sync RTD project redirects from an authoritative YAML file kept in version control. May never do anything else!


Provide an RTD API token via the environment:

$ export RTD_TOKEN=

List projects:

$ rtd projects
├── nextstrain-ncov
├── nextstrain-nextclade
├── nextstrain-augur
├── nextstrain-auspice
├── nextstrain-cli
└── nextstrain-sphinx-theme

Show a project (very sparse currently):

$ rtd projects nextstrain
nextstrain <>

Show a project’s redirects:

$ rtd projects nextstrain redirects

  Type   From URL                                                     To URL
  page   /guides/                                                     /
  page   /guides/index.html                                           /index.html
  page   /guides/install/                                             install-nextstrain.html
  page   /guides/install/augur_install.html                 
  page   /guides/install/auspice-install                    
  page   /guides/install/auspice-install.html               
  page   /guides/install/cli-install.html                   
  page   /guides/install/index.html                                   install-nextstrain.html
  page   /guides/install/local-installation.html                      install-nextstrain.html
  page   /guides/install/windows-help.html                            install-nextstrain.html
  page   /install-nextstrain.html                                     /install.html
  page   /learn/                                                      /
  page   /learn/about-nextstrain.html                                 /learn/about.html
  page   /learn/index.html                                            /index.html
  page   /reference/                                                  /
  page   /reference/formats/                                          /reference/data-formats.html
  page   /reference/formats/data-formats.html                         /reference/data-formats.html
  page   /reference/formats/index.html                                /reference/data-formats.html
  page   /reference/index.html                                        /index.html

Sync a project’s redirects:

$ rtd projects nextstrain redirects sync -f redirects.yml
Creating: page /tutorials/quickstart.html → /tutorials/running-a-workflow.html
Creating: page /tutorials/tb_tutorial.html → /tutorials/creating-a-workflow-vcf.html
Creating: page /tutorials/zika.html → /tutorials/creating-a-workflow.html


  Type   From URL                      To URL
  page   /tutorials/quickstart.html    /tutorials/running-a-workflow.html
  page   /tutorials/tb_tutorial.html   /tutorials/creating-a-workflow-vcf.html
  page   /tutorials/zika.html          /tutorials/creating-a-workflow.html


  Type   From URL   To URL

Created 3, deleted 0, kept 38.

No changes made in --dry-run mode.  Pass --wet-run for realsies.

For automation or just the full details, ask for JSON output instead of human-centered output from any command:

$ rtd --json projects
    "id": 607779,
    "name": "nextstrain",
    "created": "2020-05-28T00:25:49.630013Z",
    "modified": "2021-08-18T23:39:10.271300Z",
    "default_branch": "master",
    "default_version": "latest",
    "homepage": "",
    "language": {
      "code": "en",
      "name": "English"
    "programming_language": {
      "code": "words",
      "name": "Only Words"
    "repository": {
      "type": "git",
      "url": ""


From PyPI:

python3 -m pip install readthedocs-cli

From source:

python3 -m venv .venv
source .venv/bin/activate

python3 -m pip install --upgrade pip setuptools wheel
python3 -m pip install -e .

rtd --version

Automatic sync using GitHub Actions

We manage the RTD redirects for <> using a file in our Git repository, <>. The redirects are automatically synced to RTD via a GitHub Actions workflow that uses this CLI tool. It’s a good example of how to set up something similar for your own project. The pieces are:

  1. redirects.yml file — The redirects themselves, defined as YAML.
  2. .github/workflows/sync-redirects.yaml file — GitHub Actions workflow to sync to RTD when redirects.yml changes on the master branch.
  3. An RTD_TOKEN GitHub Actions secret containing an RTD API token.


This is still a pretty informal piece of software, but it is released to PyPI so that we can easily install it various places.

The gist of the release process is:

  1. Bump the __version__ variable (just an integer) in src/readthedocs_cli/

  2. Commit, tag, and push.

  3. Build and upload.

    You’ll need build and twine installed.

    # Clear any existing build artifacts for safety
    rm -rf dist/
    # Build source tarball and platform-agnostic wheel
    python3 -m build
    # Upload both to PyPI
    twine upload dist/*

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for readthedocs-cli, version 2
Filename, size File type Python version Upload date Hashes
Filename, size readthedocs_cli-2-py3-none-any.whl (6.8 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size readthedocs-cli-2.tar.gz (6.3 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page