wagtail-cli

Wagtail CLI

🚧 This is a prototype. Feedback very welcome! See Prototyping a new CLI for Wagtail for context.

Speed up and automate Wagtail operations with the command line. Key features:

• v3 write API client. 50+ CMS admin operations available from the terminal. To help manage local development and live sites. Manage pages, images, documents, snippets, sites, locales, redirects, and more.
• Read and search Wagtail docs as Markdown.
• Integrated agent skills with advanced progressive disclosure.
• Scaffold new Django/Wagtail projects.

Installation

Install wagtail-cli from PyPI with your preferred package manager, then use the wt CLI. Example with uv:

# Permanent install:
uv tool install wagtail-cli
# One-off usage:
uvx --from wagtail-cli wt
# Done!
wt --help

Install the skill

Optionally, install the one skill that helps agents with everything Wagtail. There are multiple options depending on your needs. To install directly as a skill, for multiple agents / harnesses:

# Directly with the CLI, global:
mkdir -p ~/.agents/skills/wagtail && wt skills get wagtail > ~/.agents/skills/wagtail/SKILL.md
# Directly with the CLI, local:
mkdir -p .agents/skills/wagtail && wt skills get wagtail > .agents/skills/wagtail/SKILL.md

As a plugin

It’s also available as a plugin, follow Agent Plugins compatible clients installation instructions, using this repository as the plugin source: wagtail/wagtail-cli. Here is an example with copilot:

copilot plugin marketplace add wagtail/wagtail-cli
copilot plugin install wagtail-cli@wagtail-cli
# Should say:
# Plugin "wagtail-cli" installed successfully. Installed 1 skill.

Quick start

Docs access

Reading the Wagtail docs needs no configuration at all:

wt docs releases/8.0    # release notes, as Markdown
wt docs api             # index of v3 API operations
wt docs search picture  # search the docs

API usage

You will need to configure the needed API credentials before using the API commands:

export WAGTAIL_CLI_BASE_URL="https://cms.example.com/api/v3/"
export WAGTAIL_CLI_TOKEN="your-api-token"

wt api whoami        # verify authentication
wt api pages list    # browse pages
wt api schema list   # discover page types

Create and publish a blog page from a Markdown file:

wt api pages create blog.BlogPage --parent /blog/ \
  --title "Hello world" --field body:@post.md --publish

Rich-text fields accept Markdown via a .md file reference: the value is sent to the API as {"format": "db_markdown", "content": …}.

Command surface

• wt api — the whole v3 API as commands: pages, images, documents, snippets, sites, locales, redirects, schema, plus wt api init and wt api whoami.
• wt docs — docs.wagtail.org as Markdown: release notes, the v3 API reference, and search.
• wt start — scaffold a new Django/Wagtail project (mirrors wagtail start / django-admin startproject, with a custom base page model as the default).
• Delegation — any other wt <command> is forwarded to ./manage.py (if present) or django-admin (when DJANGO_SETTINGS_MODULE is set), so wt also fronts Django commands like wt runserver and wt makemigrations.
• wt --version / wt --help — enhanced with detected Wagtail/Django versions and ./manage.py --help when available.

Documentation

• Getting started — end-to-end walkthrough against the demo site.
• Command reference — every command and flag.
• Configuration — config cascade, dotfiles, environment variables.
• Agent skills — the machine-readable skill published for AI agents.

Contributing

See the development guide for details.