opctl 0.1.6 → 0.1.7

package/README.md

@@ -1,5 +1,7 @@
 # opctl
 
+[![npm version](https://img.shields.io/npm/v/opctl.svg)](https://www.npmjs.com/package/opctl)
+
 `opctl` is a small local Node.js + TypeScript CLI bridge for OpenProject API v3. It uses the current user's personal API token and is read-only by default.
 
 ## Install
@@ -7,7 +9,7 @@
 Published package:
 
 - npmjs.com: `opctl`
-- current package: `opctl@0.1.4`
+- current package: `opctl@0.1.7`
 - binary: `opctl`
 
 Install globally:
@@ -81,15 +83,21 @@ opctl wp get 123 --raw-json
 opctl wp get 123 124 --table
 opctl wp get --ids 123,124 --fields id,subject,status,assignee --table
 opctl wp get --ids 123,124 --jsonl
+opctl wp get --ids 123,124 --raw-json
 ```
 
-Field selection supports `id,subject,status,type,assignee,project,href,updatedAt,description,shortDescription,attachmentsCount,lockVersion`; aliases: `title=subject`, `url=href`.
+`--raw-json` emits a single raw OpenProject object for one ID and JSONL for multiple IDs.
+
+Field selection supports `id,subject,status,type,assignee,responsible,project,href,browserUrl,updatedAt,description,shortDescription,attachmentsCount,lockVersion,priority`; aliases: `title=subject`, `url=href`.
 
 Search work packages:
 
 ```sh
 opctl wp search --project my-project --subject "pump"
 opctl wp search --project my-project --assignee-me --status open
+opctl wp search --responsible-me --open
+opctl wp search --responsible 18 --not-status "In Client Review"
+opctl wp search --filter responsible=me --filter status=o --sort updated_at:desc
 opctl wp search --open --subject "pump" --compact
 opctl wp search --subject "pump" --fields id,subject,status --json
 
@@ -97,6 +105,15 @@ opctl wp search --subject "pump" --fields id,subject,status --json
 
 If `--project` is omitted, `opctl wp search` uses `OPENPROJECT_DEFAULT_PROJECT` when set. Without either, it searches the instance-wide work package endpoint.
 
+Lookup work package types, statuses, and priorities:
+
+```sh
+opctl types --project my-project
+opctl types --json
+opctl statuses
+opctl priorities
+```
+
 List work packages assigned to the authenticated user:
 
 ```sh
@@ -105,6 +122,13 @@ opctl wp mine --open --table
 opctl wp mine --project my-project --page-size 50 --fields id,subject,status,updatedAt
 ```
 
+List open work packages accountable/responsible to the authenticated user:
+
+```sh
+opctl wp accountable
+opctl wp accountable --table --fields id,subject,status,responsible,updatedAt
+```
+
 Triage a known list:
 
 ```sh
@@ -112,6 +136,22 @@ opctl wp check 123 124
 opctl wp check --ids 123,124 --fields id,title,status,assignee,shortDescription,attachmentsCount --table
 ```
 
+Inspect and download work package attachments:
+
+```sh
+opctl wp attachments 123
+opctl wp attachments 123 --json
+opctl wp download-attachments 123 --dir /tmp/op-attachments
+opctl wp download-attachments 123 --dir /tmp/op-attachments --overwrite --json
+```
+
+Show redacted diagnostics:
+
+```sh
+opctl doctor
+opctl doctor --json
+```
+
 Pull the OpenAPI spec (defaults to the public community instance):
 
 ```sh
@@ -120,14 +160,25 @@ opctl spec pull --output openapi/my-spec.json
 opctl spec pull --url https://openproject.example.com
 ```
 
-Write-capable command:
+Write-capable commands:
 
 ```sh
+# Comment on a work package
 OPENPROJECT_ALLOW_WRITE=1 opctl wp comment 123 --dry-run "Investigating"
 OPENPROJECT_ALLOW_WRITE=1 opctl wp comment 123 "Investigating"
+
+# Create a work package (dry-run validates through /api/v3/work_packages/form)
+OPENPROJECT_ALLOW_WRITE=1 opctl wp create --project alspc --type Feature --subject "Improve Ask NAVLIN Explore messaging experience" --description-file ticket.md --dry-run
+OPENPROJECT_ALLOW_WRITE=1 opctl wp create --project alspc --type Feature --subject "S" --json < ticket.md
+
+# Use a user-story template
+opctl wp create --template user-story > ticket.md
+OPENPROJECT_ALLOW_WRITE=1 opctl wp create --project alspc --type Feature --subject "New feature" --template user-story --dry-run
 ```
 
-`wp comment` fetches the work package first and posts only when a documented HAL comment action link is present. It fails safely instead of guessing a mutation URL.
+`wp comment` and `wp create` both require `OPENPROJECT_ALLOW_WRITE=1`. `wp create --dry-run` validates through `/api/v3/work_packages/form` before any create call. Write-capable commands support `--dry-run` and avoid mutation in dry-run mode.
+
+`wp create` resolves `--type`, `--status`, and `--priority` by name (case-insensitive exact match), numeric id, or full `/api/v3/...` href. Use `opctl types`, `opctl statuses`, or `opctl priorities` to list valid values. Description can come from `--description <text>`, `--description-file <path>` (use `-` for stdin), piped stdin, or `--template user-story`.
 
 ## OpenAPI