# issue(1) - Pure Issue Management CLI

## SYNOPSIS

**issue** [*GLOBAL_OPTIONS*] *COMMAND* [*ARGS*...]

## DESCRIPTION

The **issue** command provides a dedicated CLI interface for pure issue management operations. It focuses exclusively on issue tracking, project management, and metadata operations without document processing or workflow management functionality.

This CLI is designed for users who need straightforward issue management capabilities with clean separation from development workflows and document processing systems.

## GLOBAL OPTIONS

**-h, --help**
: Show help message and exit

## COMMANDS

### Issue Browsing

**list** [*OPTIONS*]
: List all issues with optional filtering
: Shows comprehensive issue overview with status, priority, and metadata

**show** *ISSUE_NUMBER*
: Display detailed information for a specific issue
: Shows full issue description, comments, assignees, and project state

### Issue Creation and Management

**create** *TITLE* *DESCRIPTION* [*OPTIONS*]
: Create a new issue with title and description
: Supports type classification and initial priority setting

**close** *ISSUE_NUMBER* [*COMMENT*]
: Close an issue with optional closing comment
: Records completion context and updates issue status

### Project Management

**assign** *ISSUE_NUMBER* *MILESTONE_ID*
: Assign issue to a project milestone
: Links issues to project milestones for planning and tracking

**priority** *ISSUE_NUMBER* *PRIORITY*
: Set issue priority level
: Priority levels: low, medium, high, critical

**state** *ISSUE_NUMBER* *STATE*
: Set issue project state
: Common states: Todo, In Progress, Done, Review, Blocked

**milestones**
: List all project milestones
: Shows milestone progress and associated issues

### Data Export and Integration

**export** [*OPTIONS*]
: Export issues in various formats for external processing
: Supports CSV, JSON, and TSV formats with filtering

## COMMAND OPTIONS

### list

**--open**
: Show only open issues (filter closed issues)
: Focuses on active backlog items

**--format** *FORMAT*
: Output format: table, json, csv
: Default: table (human-readable format)

### create

**--type** *TYPE*
: Issue type: bug, enhancement, feature
: Default: enhancement

**--priority** *PRIORITY*
: Initial priority: low, medium, high, critical
: Sets priority at creation time

### export

**--format** *FORMAT*
: Export format: csv, json, tsv
: Default: csv

**--output** *FILE*
: Output file path (default: stdout)
: Saves export to specified file

**--filter** *FILTER*
: Filter issues: open, closed, all
: Default: all (includes all issue states)

## EXAMPLES

### Basic Issue Operations

```bash
# List all issues
issue list

# List only open issues
issue list --open

# Show specific issue details
issue show 42

# Create new bug report
issue create "Login fails" "Users cannot log in after update" --type bug --priority high

# Close completed issue
issue close 42 "Fixed in latest update"
```

### Project Management

```bash
# Set issue priority
issue priority 42 high

# Assign to milestone
issue assign 42 1

# Update project state
issue state 42 "In Progress"

# List all milestones
issue milestones
```

### Data Export and Analysis

```bash
# Export all issues to CSV
issue export --format csv --output issues.csv

# Export only open issues as JSON
issue export --format json --filter open

# Export to TSV for Unix processing
issue export --format tsv | cut -f1,3 | sort
```

### Integration with Other Tools

```bash
# Count open issues
issue list --open --format json | jq length

# Find high priority issues
issue export --format csv | grep ",high,"

# List issues by milestone
issue list --format json | jq '.[] | select(.milestone_id == 1)'
```

## CONFIGURATION

The issue CLI uses the same configuration system as other MarkiTect tools:

### Configuration Sources (priority order)
1. **Command-line options** (highest)
2. **Environment variables** (`TDDAI_*`)
3. **`.env.tddai` file** (project-specific)
4. **Default values** (lowest)

### Required Configuration Variables

**TDDAI_GITEA_URL**
: Issue tracking server URL (Gitea, GitHub, etc.)

**TDDAI_REPO_OWNER**
: Repository owner/organization name

**TDDAI_REPO_NAME**
: Repository name for issue tracking

### Optional Configuration Variables

**GITEA_API_TOKEN** or **GITHUB_TOKEN**
: API authentication token for issue operations

**TDDAI_PROJECT_ROOT**
: Project root directory for file operations

**TDDAI_DEFAULT_MILESTONE**
: Default milestone for new issues

## INTEGRATION

### With TDD Workflow

```bash
# Pure issue management with workflow integration
issue create "Implement feature" "Add new authentication method"
tddai start-issue 42  # Start TDD workflow
# ... development work ...
tddai finish-issue    # Complete TDD cycle
issue close 42 "Feature implemented with tests"
```

### With MarkiTect Document System

```bash
# Document-driven issue creation
markitect content-get requirements.md | issue create "Requirements issue" "$(cat -)"
issue assign $(issue list --format json | jq -r '.[-1].number') 1
```

### With External Systems

```bash
# Integration with CI/CD
issue export --format json | jq '.[] | select(.state == "Todo")' > todo-issues.json

# Reporting and analytics
issue export --format csv | python3 analytics.py

# Bulk operations via Unix tools
issue list --format json | jq '.[] | select(.priority == "high") | .number' | while read issue; do
    issue state $issue "High Priority Review"
done
```

## EXIT STATUS

**0**
: Success

**1**
: General error (invalid arguments, operation failed)

**2**
: Configuration error (missing config, invalid values)

**3**
: API error (network issues, authentication failure)

**4**
: Data format error (invalid JSON, CSV parsing failure)

## ENVIRONMENT

**TDDAI_GITEA_URL**
: Issue tracking server URL

**TDDAI_REPO_OWNER**
: Repository owner name

**TDDAI_REPO_NAME**
: Repository name

**GITEA_API_TOKEN**
: Gitea API authentication token

**GITHUB_TOKEN**
: GitHub API authentication token

**TDDAI_VERBOSE**
: Enable verbose output (any non-empty value)

## FILES

**`.env.tddai`**
: Project configuration file

**`.tddai/`**
: Local project data directory

**`~/.tddai/`**
: User configuration directory

## COMPARISON WITH OTHER CLIS

### issue vs tddai vs markitect

**issue CLI**
: Pure issue management - listing, creating, closing, project organization
: Best for: Project managers, issue triaging, bulk operations

**tddai CLI**
: TDD workflow management - workspace, testing, development lifecycle
: Best for: Developers working on specific issues, test-driven development

**markitect CLI**
: Document processing - templates, schemas, content analysis
: Best for: Technical writers, document generation, content management

### When to Use issue CLI

- Project planning and issue organization
- Bulk issue operations and reporting
- Issue metadata management
- Integration with external project management tools
- Simple issue browsing and status updates

### When to Use tddai CLI Instead

- Starting development work on an issue
- TDD workflow and test coverage analysis
- Workspace management and development context
- Issue completion with testing verification

### When to Use markitect CLI Instead

- Document generation and template processing
- Schema validation and content analysis
- Performance monitoring and benchmarking
- Database operations and caching

## SEE ALSO

**tddai**(1), **markitect**(1)

Related documentation:
- Issue Management Guide
- Project Organization Best Practices
- CLI Integration Patterns
- Configuration Reference Manual

## BUGS

Report bugs at project issue tracker

## AUTHORS

MarkiTect Project development team

## COPYRIGHT

Copyright (c) 2025 MarkiTect Project. Licensed under MIT License.