openproject（openproject 命令行）

OpenProject CLI

Single-command interface for OpenProject. All operations via op.py.

Quick Start

# From skill directory:
cd skills/openproject

# 1. First time: init config (only once per project)
uv run python op.py init 13

# 2. Check status
uv run python op.py status

# 3. Start working
uv run python op.py wp list --status open

Setup

cd skills/openproject
uv sync

Configure .env:

OPENPROJECT_URL=https://your-instance.com
OPENPROJECT_API_KEY=your-api-key

API key from: OpenProject → My Account → Access Tokens

CLI Commands

All commands: cd skills/openproject && uv run python op.py <command>

System

Work Packages (wp)

wp list filters: --status open|closed|all|"name" --type "Task" --assignee "name" --parent N --project N --limit N

wp create/update: --subject --type --status --priority --assignee --responsible --description --parent --version --start-date --due-date --estimated-hours --done --cf "key=val"

relation types: relates|blocks|blocked|precedes|follows|duplicates|includes|partof|requires

Time Tracking (time)

time log: --hours N (required) --comment "..." --date YYYY-MM-DD --activity N

time list: --wp N --user "name" --date --from-date --to-date --limit N

time update: --hours N --comment "..." --date --wp N --activity N

Projects (project)

project create: --name --identifier --description --parent N --public

Notifications (notif)

notif reasons: mentioned|assigned|watched|responsible|commented|created|prioritized|scheduled

Users (user)

Lookups (from config cache)

Examples

# List open tasks assigned to Hung NB
uv run python op.py wp list --status open --assignee "Hung NB" --type Task

# Create a bug
uv run python op.py wp create --subject "Login page broken" --type Bug --priority High

# Update status and assignee
uv run python op.py wp update 675 --status "In progress" --assignee "Hung NB"

# Add comment to WP
uv run python op.py wp comment 675 --message "Fixed in commit abc123"

# Create a relation: WP 100 blocks WP 200
uv run python op.py wp add-relation 100 200 --type blocks

# Log 2.5 hours
uv run python op.py time log 675 --hours 2.5 --comment "Fixed login bug"

# Get today's logged time
uv run python op.py time today

# Time entries for date range
uv run python op.py time list --from-date 2026-02-01 --to-date 2026-02-28 --user "Tuan HV"

# Check unread notifications
uv run python op.py notif count

# List unread notifications
uv run python op.py notif list --unread --limit 10

# Get current user
uv run python op.py user me

# List project versions
uv run python op.py project versions

Output Format

All commands output JSON. Example:

{"count": 2, "work_packages": [{"id": 675, "subject": "Login page", "type": "Bug", "status": "In progress"}]}

⚠️ Important Notes

• Name resolution uses config cache. Refresh with: uv run python op.py init <project_id>
• Custom fields are project/type specific. Use op.py config to see available ones.
• op.py auto-loads .env — no manual load_dotenv() needed.

Advanced: Python API

For complex operations not covered by CLI, use Python packages directly:

uv run python -c "
from openproject_work_packages import list_work_packages
for wp in list_work_packages(project_id=13):
    print(wp['subject'])
"

Sub-package docs:

Python API Gotchas

• list_* functions return generators → use list(...) to convert
• Time hours is ISO 8601 duration (e.g., PT1H30M) → use parse_duration()
• update_work_package() auto-fetches lockVersion if not provided
• get_schema() requires both project_id AND type_id