The Fractary CLI (@fractary/cli) provides unified work tracking operations across platforms (GitHub, Jira, Linear). Skills use this helper to invoke CLI commands and parse JSON responses.

CLI Invocation Pattern

Skills should invoke the CLI using this pattern:

# Direct CLI invocation (recommended)
result=$(fractary work <subcommand> [options] --json 2>&1)
exit_code=$?

# Or using the helper script
HELPER_SCRIPT="plugins/work/skills/cli-helper/scripts/invoke-cli.sh"
result=$(bash "$HELPER_SCRIPT" <subcommand> [options] --json 2>&1)
exit_code=$?

Available CLI Commands

Issue Operations

fractary work issue create --title "Title" --body "Body" --labels "a,b" --json
fractary work issue fetch <number> --json
fractary work issue update <number> --title "New title" --json
fractary work issue close <number> --json
fractary work issue search --state open --limit 10 --json

Comment Operations

fractary work comment create <issue_number> --body "Comment text" --json
fractary work comment list <issue_number> --json

Label Operations

fractary work label add <issue_number> --labels "label1,label2" --json
fractary work label remove <issue_number> --labels "label1" --json
fractary work label list --json

Milestone Operations

fractary work milestone list --json
fractary work milestone set <issue_number> --milestone "v1.0" --json

Response Format

CLI returns JSON with consistent structure:

Success Response

{
  "status": "success",
  "data": {
    // Operation-specific data
  }
}

Error Response

{
  "status": "error",
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable message",
    "details": {}
  }
}

Mapping CLI Response to Plugin Response

Skills should map CLI responses to the standard plugin response format:

# Parse CLI JSON response
cli_response=$(fractary work issue create --title "$TITLE" --json 2>&1)
cli_status=$(echo "$cli_response" | jq -r '.status')

if [ "$cli_status" = "success" ]; then
    # Extract data and build plugin response
    issue_id=$(echo "$cli_response" | jq -r '.data.number')
    issue_url=$(echo "$cli_response" | jq -r '.data.url')

    # Return plugin format
    cat <<EOF
{
  "status": "success",
  "operation": "create-issue",
  "result": {
    "id": "$issue_id",
    "identifier": "#$issue_id",
    "url": "$issue_url",
    "platform": "github"
  }
}
EOF
else
    # Extract error and return plugin error format
    error_code=$(echo "$cli_response" | jq -r '.error.code // "UNKNOWN_ERROR"')
    error_msg=$(echo "$cli_response" | jq -r '.error.message // "Unknown error"')

    cat <<EOF
{
  "status": "error",
  "operation": "create-issue",
  "code": "$error_code",
  "message": "$error_msg"
}
EOF
fi

Error Handling

Map CLI errors to plugin error codes:

Dependencies

• @fractary/cli >= 0.3.0 - Fractary CLI with work module
• jq - JSON parsing
• bash - Shell execution

Usage by Other Skills

Skills reference this helper by:

1. Direct CLI invocation (recommended):

   fractary work issue create --title "Title" --json
   

2. Using helper script (for version checking):

   bash plugins/work/skills/cli-helper/scripts/invoke-cli.sh issue create --title "Title" --json
   

The helper script adds:

• CLI availability check
• Version requirement validation
• Consistent error messages

Testing

# Test CLI availability
fractary --version

# Test work module
fractary work --help

# Test JSON output
fractary work issue fetch 1 --json