afv-library/skills/dx-devops-work-item-manage/references/cli-commands.md

DevOps Center Work Item CLI Commands Reference

Complete reference for sf devops work-item CLI commands with JSON output schemas and common patterns.

Command Summary

Command	Purpose	Required Flags	Optional Flags
sf devops work-item list	List all work items in a project	--project-id	--api-version
sf devops work-item create	Create new work item	--project-id, --subject	--description, --api-version
sf devops work-item update	Update work item fields or status	--work-item-name OR --work-item-id, plus at least one of: --subject, --description, --status	--api-version
sf devops review create	Create pull request for work item	--work-item-name OR --work-item-id	--api-version

All commands support --json for structured output and --target-org <alias> for multi-org scenarios.

Org Authentication: Before running any DevOps Center commands, verify org authentication:

sf org display --json

If no default org is set or the user wants to target a specific org, add --target-org <alias> to all commands.

---

List Work Items

Basic Usage

sf devops work-item list --project-id <project-id> --json

Example

# List all work items for project 1Qg000000000001
sf devops work-item list --target-org my-devops-org --project-id 1Qg000000000001 --json

JSON Output Schema

{
  "status": 0,
  "result": [
    {
      "id": "0Wx000000000001AAA",
      "name": "WI-000001",
      "subject": "Fix login bug",
      "description": "Users can't log in on mobile devices",
      "branch": "feature/fix-login",
      "environment": "dev-scratch-1",
      "repositoryUrl": "https://github.com/org/repo",
      "status": "In Progress",
      "lastModifiedDate": "2026-07-22T10:30:00.000Z",
      "createdDate": "2026-07-20T08:15:00.000Z"
    },
    {
      "id": "0Wx000000000002AAA",
      "name": "WI-000002",
      "subject": "Add dark mode",
      "description": "",
      "branch": "feature/dark-mode",
      "environment": "dev-scratch-2",
      "repositoryUrl": "https://github.com/org/repo",
      "status": "Ready to Promote",
      "lastModifiedDate": "2026-07-21T15:45:00.000Z",
      "createdDate": "2026-07-19T09:00:00.000Z"
    }
  ]
}

Key Fields

• id: Salesforce record ID (use with --work-item-id)
• name: Human-readable work item name like WI-000001 (use with --work-item-name)
• subject: Title of the work item
• description: Detailed description (may be empty string)
• branch: Git branch associated with this work item
• environment: Development environment name
• status: Current work item status

---

Create Work Item

Required Fields

sf devops work-item create \
  --project-id <project-id> \
  --subject "<subject>" \
  --json

With Optional Description

sf devops work-item create \
  --project-id 1Qg000000000001 \
  --subject "Fix login bug" \
  --description "Users can't log in on mobile devices" \
  --json

JSON Output Schema

{
  "status": 0,
  "result": {
    "id": "0Wx000000000003AAA",
    "name": "WI-000003",
    "subject": "Fix login bug",
    "description": "Users can't log in on mobile devices",
    "branch": "feature/fix-login-bug",
    "environment": "dev-scratch-3",
    "repositoryUrl": "https://github.com/org/repo",
    "status": "New",
    "createdDate": "2026-07-22T11:00:00.000Z"
  }
}

---

Update Work Item

Update Subject

sf devops work-item update \
  --work-item-name WI-000001 \
  --subject "Fix critical login bug" \
  --json

Update Description

sf devops work-item update \
  --work-item-name WI-000001 \
  --description "Updated description with repro steps: 1. Open app on iOS 2. Tap login..." \
  --json

Update Status

sf devops work-item update \
  --work-item-name WI-000001 \
  --status "In Progress" \
  --json

Valid status values (exact strings):

• "In Progress" (with space and proper capitalization)
• "Ready to Promote" (with space and proper capitalization)

Update Multiple Fields

sf devops work-item update \
  --work-item-name WI-000001 \
  --subject "Fix critical login bug [P0]" \
  --description "Updated with repro steps" \
  --status "In Progress" \
  --json

Using Work Item ID Instead of Name

sf devops work-item update \
  --work-item-id 0Wx000000000001AAA \
  --status "Ready to Promote" \
  --json

Note: Prefer --work-item-name (WI-000001) over --work-item-id when available — names are human-readable and easier to reference.

JSON Output Schema

{
  "status": 0,
  "result": {
    "id": "0Wx000000000001AAA",
    "name": "WI-000001",
    "subject": "Fix critical login bug [P0]",
    "description": "Updated with repro steps",
    "status": "In Progress",
    "lastModifiedDate": "2026-07-22T11:15:00.000Z"
  }
}

---

Error Handling

Common Error Scenarios

Work item not found:

{
  "status": 1,
  "name": "NOT_FOUND",
  "message": "The requested resource does not exist",
  "exitCode": 1
}

Invalid status value:

{
  "status": 1,
  "name": "INVALID_STATUS",
  "message": "Invalid status value. Allowed values: 'In Progress', 'Ready to Promote'",
  "exitCode": 1
}

Missing required field (create):

{
  "status": 1,
  "name": "RequiredFlagsError",
  "message": "Missing required flag --subject",
  "exitCode": 1
}

Missing update field:

{
  "status": 1,
  "name": "RequiredFlagsError",
  "message": "At least one of --subject, --description, or --status must be provided",
  "exitCode": 1
}

Project not found:

{
  "status": 1,
  "name": "NOT_FOUND",
  "message": "Project with ID 1Qg000000000999 does not exist or is not accessible",
  "exitCode": 1
}

Authentication failure:

{
  "status": 1,
  "name": "NoOrgFound",
  "message": "No org configuration found for target-org. Run 'sf org login web' to authenticate.",
  "exitCode": 1
}

---

Parsing JSON Output

Extract Work Item Name (create operation)

# Store work item name in a variable
WORK_ITEM_NAME=$(sf devops work-item create \
  --project-id 1Qg000000000001 \
  --subject "Test WI" \
  --json | jq -r '.result.name')

echo "Created work item: $WORK_ITEM_NAME"
# Output: Created work item: WI-000004

Check for Empty List

# Count returned work items
COUNT=$(sf devops work-item list --project-id 1Qg000000000001 --json | jq '.result | length')

if [ "$COUNT" -eq 0 ]; then
  echo "No work items found for this project"
else
  echo "Found $COUNT work items"
fi

Extract Specific Fields

# List work item names and subjects
sf devops work-item list --project-id 1Qg000000000001 --json | \
  jq -r '.result[] | "\(.name): \(.subject)"'

# Output:
# WI-000001: Fix login bug
# WI-000002: Add dark mode

Filter by Status

# Find all work items with "Ready to Promote" status
sf devops work-item list --project-id 1Qg000000000001 --json | \
  jq -r '.result[] | select(.status == "Ready to Promote") | "\(.name): \(.subject)"'

---

Idempotent Create Pattern

To avoid duplicate work items, check for existing work items with the same subject before creating:

PROJECT_ID="1Qg000000000001"
SUBJECT="Fix login bug"

# Check if work item with subject exists
EXISTING_NAME=$(sf devops work-item list \
  --project-id "$PROJECT_ID" \
  --json | \
  jq -r ".result[] | select(.subject == \"$SUBJECT\") | .name" | head -n1)

if [ -n "$EXISTING_NAME" ]; then
  echo "Work item already exists: $EXISTING_NAME"
else
  # Create new work item
  NEW_NAME=$(sf devops work-item create \
    --project-id "$PROJECT_ID" \
    --subject "$SUBJECT" \
    --json | jq -r '.result.name')
  echo "Created new work item: $NEW_NAME"
fi

---

Authentication Requirements

All sf devops work-item commands require:

1. Authenticated org: sf org login web or JWT auth
2. DevOps Center enabled: Org must have DOCe provisioned
3. Appropriate permissions: User must have access to the project

Verify authentication before running commands:

sf org display --target-org <alias> --json

If authentication fails, the user must run:

sf org login web --set-default --alias <alias>

---

Create Pull Request

Basic Usage

sf devops review create \
  --work-item-name <WI-name> \
  --json

Example with Work Item Name

sf devops review create \
  --work-item-name WI-000001 \
  --json

Example with Work Item ID

sf devops review create \
  --work-item-id 0Wx000000000001AAA \
  --json

Note: Prefer --work-item-name (WI-000001) over --work-item-id when available — names are human-readable and easier to reference.

JSON Output Schema

{
  "status": 0,
  "result": {
    "id": "0PR000000000001AAA",
    "workItemId": "0Wx000000000001AAA",
    "workItemName": "WI-000001",
    "pullRequestUrl": "https://github.com/org/repo/pull/42",
    "pullRequestNumber": 42,
    "pullRequestStatus": "open",
    "createdDate": "2026-07-23T10:00:00.000Z"
  }
}

Key Fields

• pullRequestUrl: Direct link to the PR in VCS (GitHub or Bitbucket)
• pullRequestNumber: PR number in the VCS system
• pullRequestStatus: Current status (typically "open" at creation)
• workItemName: Work item the PR was created for
• id: Salesforce record ID for the review record

How It Works

• Uses VCS credentials stored in DevOps Center org (not local git auth)
• Creates PR from work item's branch to the pipeline's base branch
• Works with GitHub and Bitbucket
• Requires VCS connection configured in DevOps Center UI first

Error Scenarios

VCS credentials not configured:

{
  "status": 1,
  "name": "VCS_NOT_CONFIGURED",
  "message": "VCS connection not configured for this project. Configure in DevOps Center UI first.",
  "exitCode": 1
}

Work item not found:

{
  "status": 1,
  "name": "NOT_FOUND",
  "message": "Work item WI-000999 does not exist or is not accessible",
  "exitCode": 1
}

PR already exists:

{
  "status": 1,
  "name": "PR_ALREADY_EXISTS",
  "message": "A pull request already exists for work item WI-000001",
  "exitCode": 1
}

---

Getting Project ID

If the user doesn't provide a project ID, list available projects first:

sf devops project list --json | jq -r '.result[] | "\(.id): \(.name)"'

Output:

1Qg000000000001: Project Alpha
1Qg000000000002: Project Beta

Then use the ID in subsequent work item commands.