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

Command	Description
`status`	Check connection + config status
`init <project_id>`	Init config for project (once)
`config`	Show full config (types, statuses, members, custom fields)

Work Packages (`wp`)

Command	Description
`wp list [options]`	List work packages
`wp get <id>`	Get single work package
`wp create --subject "..." [options]`	Create work package
`wp update <id> [options]`	Update work package
`wp delete <id>`	Delete work package
`wp comment <id> --message "..."`	Add comment
`wp activities <id>`	List activities/comments
`wp relations <id>`	List WP relations
`wp add-relation <from> <to> --type blocks`	Create relation
`wp del-relation <relation_id>`	Delete relation
`wp schema --type-id N`	Get form schema

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"

Time Tracking (`time`)

Command	Description
`time log <wp_id> --hours N`	Log time entry
`time list [options]`	List time entries
`time today`	Today's entries for current user
`time get <id>`	Get time entry
`time update <id> [options]`	Update time entry
`time delete <id>`	Delete time entry
`time activities`	List activity types

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`)

Command	Description
`project list`	List all projects
`project get <id>`	Get project
`project create --name "..."`	Create project
`project update <id> [options]`	Update project
`project delete <id>`	Delete project
`project versions [--id N]`	List versions
`project categories [--id N]`	List categories

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

Notifications (`notif`)

Command	Description
`notif list [--unread] [--reason X]`	List notifications
`notif count`	Unread count
`notif read <id>`	Mark as read
`notif unread <id>`	Mark as unread
`notif read-all`	Mark all read

Users (`user`)

Command	Description
`user list`	List all users
`user get <id>`	Get user
`user me`	Current user info

Lookups (from config cache)

Command	Description
`members`	Project members (name + user_id)
`types`	WP types (Task, Bug, etc.)
`statuses`	All statuses
`priorities`	All priorities

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:

Package	SKILL.md
`openproject_core`	`openproject-core/SKILL.md`
`openproject_projects`	`openproject-projects/SKILL.md`
`openproject_work_packages`	`openproject-work-packages/SKILL.md`
`openproject_time`	`openproject-time/SKILL.md`
`openproject_users`	`openproject-users/SKILL.md`
`openproject_documents`	`openproject-documents/SKILL.md`
`openproject_queries`	`openproject-queries/SKILL.md`
`openproject_notifications`	`openproject-notifications/SKILL.md`
`openproject_admin`	`openproject-admin/SKILL.md`

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

openproject