markitect-main/docs/manuals/issue.1.md

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

# 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

# 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

# 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

# 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

# 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

# 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

# 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.