mantis-cli

A small, friendly command line client for the Mantis Bug Tracker REST API.

Manage issues, projects, users and server config from your terminal, with pretty tables by default and raw JSON on demand.

Install

pip install mantishub-cli

This installs the mantis command.

From source

git clone git@github.com:shooding/mantishub-cli.git
cd mantishub-cli
pip install -e ".[dev]"

Configure

mantis needs the base URL of your Mantis instance and an API token. Create a token in Mantis under My Account → API Tokens → Create API Token.

Copy the example env file and fill it in:

cp .env.example .env
# edit .env

MANTIS_URL=https://your-instance.mantishub.io
MANTIS_API_KEY=your-api-token

mantis reads .env from the current directory automatically. Real environment variables and the --url / --token flags take precedence over .env, in that order.

Usage

mantis --help

Global options:

Option	Env var	Description
--url	MANTIS_URL	Base URL of the Mantis instance.
--token	MANTIS_API_KEY	API token.
--json	—	Output raw JSON instead of tables.

Issues

# List issues (optionally scoped / filtered / paginated)
mantis issue list
mantis issue list --project-id 1 --page-size 50
mantis issue list --filter assigned        # assigned | reported | monitored | unassigned

# Show one issue
mantis issue get 42
mantis issue get 42 --select id,summary,description

# Create an issue
mantis issue create --project-id 1 \
  --summary "Login button is misaligned" \
  --description "On mobile the button overlaps the footer." \
  --priority high --severity minor

# Update an issue
mantis issue update 42 --status resolved --handler vboctor

# Notes and tags
mantis issue note-add 42 --text "Reproduced on iOS 17." --private
mantis issue note-delete 42 7
mantis issue tag-add 42 --tag regression --tag mobile

# Monitor / delete
mantis issue monitor 42
mantis issue delete 42 --yes

Projects

mantis project list
mantis project get 1
mantis project create --name "New App" --description "Greenfield project"
mantis project delete 3 --yes

Users

mantis user me
mantis user get 5          # by id
mantis user get vboctor    # by username

Server config

mantis config csv_separator
mantis config status_colors priority_enum_string

JSON output

Add --json to any command to get the raw API response, handy for piping into jq:

mantis --json issue list --project-id 1 | jq '.[].summary'

Use as an AI agent skill

This repo ships an Agent Skill that teaches AI coding agents how to drive the mantis command. The same SKILL.md works with Claude Code, OpenAI Codex, and OpenCode — see skills/README.md for one-line install instructions for each.

Development

pip install -e ".[dev]"
pytest                 # run the test suite (tests/*_test.py)

Tests mock all HTTP traffic with responses, so no live Mantis instance is required.

Publishing

Build and upload to PyPI (requires a PyPI API token):

export TWINE_USERNAME=__token__
export TWINE_PASSWORD=pypi-XXXX

./scripts/build.sh            # build sdist + wheel into dist/
./scripts/publish.sh          # build, validate, and upload to PyPI
./scripts/publish.sh --test   # upload to TestPyPI instead

License

MIT — see LICENSE.