tegwick
bce5a57593
- Created specialized test-fixing agent to analyze and fix failing tests - Re-added issues group to markitect CLI for unified access alongside dedicated CLIs - Updated CLI consolidation tests to reflect new architecture (unified + specialized) - Removed unnecessary test_plugin_assigns_sequential_issue_numbers (local plugin not actively used) - Added comprehensive manual pages for all three CLIs (markitect, tddai, issue) - Enhanced CLI integration tests with 40+ test cases covering functionality and regression prevention - Ensured clean test suite with all critical tests passing Architecture: markitect provides unified interface while tddai/issue CLIs offer specialized access Test Coverage: 801 tests with comprehensive CLI validation and functionality verification 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
337 lines
7.6 KiB
Markdown
337 lines
7.6 KiB
Markdown
# 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. |