Work items are the core executable unit in OpenIndex. The oi work-item command group covers the full lifecycle: listing, creating, updating, transitioning through workflow stages, scheduling, collaborating via comments, and managing attachments, dependencies, and custom fields.
List and get
oi work-item list [flags]
oi work-item get <key>
oi work-item agent-context <key>
oi work-item hierarchy <key>
oi work-item delete <key>
agent-context returns the agent-oriented workflow bundle for a work item. In --json mode it returns the full backend payload from /browse/:key/agent-context. In human mode it summarises the current goal, allowed exits, blocked exits, and required fields.
List filters
| Flag | Description |
|---|
--key | Filter by work item key |
--kind | project, task, or sub_task |
--domain-id | Filter by domain |
--owner-user-id | Filter by owner user ID |
--assigned-to-me | true or false |
--personal-only | true or false |
--parent-key | Parent key (aliases: --project-key, --task-key) |
--workflow-id | Filter by workflow |
--status | Filter by status |
--priority | Filter by priority |
--execution-target | human, agent, or either |
--active-agent-id | Filter by active agent ID (supports none) |
--resolution | unresolved, resolved, or cancelled |
--resolved-after | RFC3339 timestamp |
--schedule-granularity | none, date, or datetime |
--search | Full-text search |
Create
oi work-item create --kind <project|task|sub_task> --title <text> [flags]
| Flag | Description |
|---|
--domain-id | Domain to create the item in |
--parent-key | Parent work item key (aliases: --project-key, --task-key) |
--workflow-id | Workflow to assign |
--description | Item description |
--status | Initial status |
--priority | Initial priority |
--execution-target | human or agent |
--owner-user-id | Owner user ID |
--assignee-user-id | Assignee user ID |
--objective-state | Objective state value |
Update
oi work-item update <key> [flags]
| Flag | Description |
|---|
--title | New title |
--description | New description |
--status | New status |
--priority | New priority |
--workflow-id | Reassign workflow |
--execution-target | human or agent |
--owner-user-id | New owner user ID |
--assignee-user-id | New assignee user ID |
--resolution | unresolved, resolved, or cancelled |
--active-agent-id | Set active agent ID |
--clear-agent | Clear the active agent field |
--error | Set error message |
--attempt | Set attempt counter |
Claim and complete
oi work-item claim <key> --to-status <status> [--agent-id <id>]
oi work-item complete <key> --to-status <status> [--agent-id <id>]
oi work-item done <key> [--to-stage <stage>]
claim requires a valid workflow transition from the current status.complete requires a valid transition to a terminal status, clears active agent fields, and marks the item as resolved.done auto-progresses through valid stage gates to a completion stage (completed by default).
If complete fails because the target status is not terminal, the CLI suggests oi work-item progress --to-stage ... as a next step.
Progress through stage gates
Use progress to advance a work item through a workflow stage gate:
oi work-item progress <key> --stage-gate-key <gate-key> [flags]
oi work-item progress <key> --to-stage <stage-key> [flags]
| Flag | Description |
|---|
--stage-gate-key | Explicit gate key from transitions output |
--to-stage | Resolve gate from current availableStageGates |
--accept-requirements-text | Required when gate requirements mode is text |
--checked-requirement-item | Repeat for each completed checklist requirement |
--note | Optional audit note |
Transitions
Inspect valid transitions and available stage gates for a work item:
oi work-item transitions <key>
claim, complete, or progress when you are unsure of the allowed next states.
Schedule placement
oi work-item schedule <key> --date <YYYY-MM-DD>
oi work-item schedule <key> --start <RFC3339> --end <RFC3339>
oi work-item schedule <key> --clear
| Form | Schedule granularity |
|---|
--date | Date-only (scheduleGranularity: date) |
--start + --end | Timed (scheduleGranularity: datetime) |
--clear | Returns item to backlog (scheduleGranularity: none) |
Hierarchy
oi work-item hierarchy <key>
oi work-item comment list <key>
oi work-item comment create <key> --body <text> [--visibility internal|external]
oi work-item comment update <key> --comment-id <id> --body <text>
oi work-item comment delete <key> --comment-id <id>
--body is required for create and update.--visibility defaults to internal. Pass external to share the comment outside the team.
Custom fields
oi work-item custom-fields get <key>
oi work-item custom-fields update <key> --values-json '{"field_key":"value"}'
--values-json accepts a JSON object keyed by workflow custom field key.
Attachments
oi work-item attachment list <key>
oi work-item attachment link <key> --url <https://...> [--filename <name>]
oi work-item attachment upload <key> --file </path/file> [--filename <name>] [--mime-type <mime>] [--checksum <value>]
oi work-item attachment delete <key> --attachment-id <id>
Dependencies
oi work-item dependency list <key>
oi work-item dependency create <key> --to-key <other-key>
oi work-item dependency delete <key> --dependency-id <id>
Audit log
oi work-item audit list <key> [filters]
oi work-item audit export <key> [--format json|csv] [--output <path>] [filters]
--output to write directly to a file.