Managing Work Items

Work items are the core unit of work in OpenIndex. Every piece of work — whether a large initiative, an individual task, or a granular step — lives as a work item with a consistent structure and key. OpenIndex has three kinds of work items that follow the hierarchy Project → Task → Sub-task:

Project

A container for larger objectives inside a domain.

Task

A standard executable work item under a project.

Sub-task

A granular step under a task, keyed as DOMAIN-123.1.

Work-item keys are domain-scoped and sequential — for example, OPS-42 or OPS-42.1 for a sub-task.

Creating a work item

Via CLI

# Create a task in a domain
oi work-item create --kind task --title "My task" --domain-id <id>

# Create a sub-task under a parent
oi work-item create --kind sub_task --title "Sub-task" --parent-key ABC-123

Additional create flags:

Flag	Description
`--workflow-id`	Attach a workflow at creation time
`--description`	Body text for the work item
`--status`	Initial status value
`--priority`	Priority level
`--execution-target`	`human`, `agent`, or `either`
`--assignee-user-id`	Assign to a specific user
`--owner-user-id`	Set the owner

Via API

POST /browse with a JSON body:

{
  "kind": "task",
  "title": "My task",
  "domainId": "<domain-id>",
  "parentKey": "ABC-123",
  "workflowId": "<workflow-id>",
  "description": "Optional description",
  "status": "backlog",
  "priority": "medium",
  "executionTarget": "agent"
}

Listing work items

oi work-item list

Filter the list with any combination of these flags:

Flag	Description
`--kind`	`project`, `task`, or `sub_task`
`--domain-id`	Scope to a domain
`--status`	Filter by status value
`--priority`	Filter by priority
`--execution-target`	`human`, `agent`, or `either`
`--search`	Full-text search across titles
`--parent-key`	List children of a specific work item
`--assigned-to-me`	Show only items assigned to you
`--resolution`	`unresolved`, `resolved`, or `cancelled`

Getting a work item

oi work-item get ABC-123

This returns the full work item record, including its current status, priority, workflow assignment, schedule, and metadata. The equivalent API call is GET /browse/:key.

Updating a work item

oi work-item update ABC-123 --title "New title"

Available update flags:

Flag	Description
`--title`	Update the title
`--description`	Update the body
`--status`	Change the status
`--priority`	Change the priority
`--workflow-id`	Reassign to a different workflow
`--execution-target`	Change execution target
`--assignee-user-id`	Reassign to a user

The equivalent API call is PATCH /browse/:key.

Status changes must respect valid workflow transitions. Use oi work-item transitions ABC-123 to see which statuses are reachable from the current state.

Scheduling a work item

You can schedule work to a specific date or a timed block, or clear a schedule to move it back to the backlog.

# Date-only scheduling
oi work-item schedule ABC-123 --date 2026-03-01

# Timed scheduling
oi work-item schedule ABC-123 --start 2026-03-01T15:00:00Z --end 2026-03-01T16:00:00Z

# Clear schedule (back to backlog)
oi work-item schedule ABC-123 --clear

Scheduled work items appear alongside external calendar events in the calendar view.

Managing comments

Comments let you leave notes and collaborate on a work item. You can control visibility to keep some notes internal.

# Create a comment
oi work-item comment create ABC-123 --body "This is a comment"

# Create an external-visible comment
oi work-item comment create ABC-123 --body "Update for the customer" --visibility external

# List comments
oi work-item comment list ABC-123

# Update a comment
oi work-item comment update ABC-123 --comment-id <id> --body "Updated text"

# Delete a comment
oi work-item comment delete ABC-123 --comment-id <id>

The --visibility flag accepts internal (default) or external. External comments are visible in email conversation threads.

Managing attachments

You can attach local files or link external URLs to a work item.

# Upload a file
oi work-item attachment upload ABC-123 --file ./report.pdf

# Link a URL
oi work-item attachment link ABC-123 --url "https://example.com/doc" --filename "Design doc"

# List attachments
oi work-item attachment list ABC-123

# Delete an attachment
oi work-item attachment delete ABC-123 --attachment-id <id>

Managing dependencies

Track relationships between work items using dependencies.

# Create a dependency
oi work-item dependency create ABC-123 --to-key DEF-456

# List dependencies
oi work-item dependency list ABC-123

# Delete a dependency
oi work-item dependency delete ABC-123 --dependency-id <id>

The API equivalents are POST /browse/:key/dependencies, GET /browse/:key/dependencies, and DELETE /browse/:key/dependencies/:dependencyId.

Managing categories

Categories are domain-scoped labels for organizing work items.

# Assign a category
oi work-item categories add ABC-123 --category-id <id>

# Remove a category
oi work-item categories remove ABC-123 --category-id <id>

The API equivalents are POST /browse/:key/categories and DELETE /browse/:key/categories/:categoryId.

Viewing hierarchy

See the full parent-child tree for a work item:

oi work-item hierarchy ABC-123

The API equivalent is GET /browse/:key/hierarchy.

Audit history

Every mutation to a work item is recorded. To inspect the change history:

oi work-item audit list ABC-123

You can also export the audit log:

oi work-item audit export ABC-123 --format json --output ./audit.json

Deleting a work item

oi work-item delete ABC-123

The API equivalent is DELETE /browse/:key. Deletion is permission-checked and key-targeted.

Deleting a work item is permanent. There is no undo.

Get Started

Core Concepts

Guides

CLI Reference

Configuration

Managing Work Items

Project

Task

Sub-task

Creating a work item

Via CLI

Via API

Listing work items

Getting a work item

Updating a work item

Scheduling a work item

Managing comments

Managing attachments

Managing dependencies

Managing categories

Viewing hierarchy

Audit history

Deleting a work item

Project

Task

Sub-task

​Creating a work item

​Via CLI

​Via API

​Listing work items

​Getting a work item

​Updating a work item

​Scheduling a work item

​Managing comments

​Managing attachments

​Managing dependencies

​Managing categories

​Viewing hierarchy

​Audit history

​Deleting a work item

Creating a work item

Via CLI

Via API

Listing work items

Getting a work item

Updating a work item

Scheduling a work item

Managing comments

Managing attachments

Managing dependencies

Managing categories

Viewing hierarchy

Audit history

Deleting a work item