IssueDB Documentation

Welcome to the official documentation for IssueDB, a command-line issue tracking system for software development projects. IssueDB provides simple, concrete issue management directly from your terminal with a per-directory database model.

Getting Started

• Installation
  • Prerequisites
  • Installing from PyPI
  • Installing from Source
  • Development Installation
  • Verification
  • Database Location
  • Shell Completion
  • Upgrading
  • Uninstalling
• Quickstart Guide
  • Your First Issue
  • Listing Issues
  • Working on Issues
  • Getting the Next Issue
  • Adding Comments
  • Closing Issues
  • Marking Issues as Won’t Do
  • Searching Issues
  • JSON Output
  • Viewing Statistics
  • Audit Trail
  • Deleting Issues
  • Clearing All Issues
  • Complete Workflow Example
  • What’s Next?

User Guide

• CLI Reference
  • Global Options
  • Issue Management Commands
  • Memory Commands
  • Lesson Commands
  • Tag Commands
  • Link Commands
  • Comment Commands
  • Bulk Operations
  • Reporting Commands
  • Dependency Commands
  • Code Reference Commands
  • Time Tracking Commands
  • Workspace Commands
  • Duplicate Detection Commands
  • Template Commands
  • Bulk Pattern Commands
  • Administrative Commands
  • Exit Codes
• Comments
  • Overview
  • Adding Comments
  • Viewing Comments
  • Deleting Comments
  • Common Patterns
  • Comments and Issue Deletion
  • Best Practices
  • API Reference
• Bulk Operations
  • Overview
  • Bulk Update (Filter-Based)
  • Bulk Create
  • Bulk Update (JSON)
  • Bulk Close
  • Error Handling
  • Use Cases
  • Performance
• Audit Logging
  • Overview
  • Viewing Audit Logs
  • Audit Log Structure
  • Action Types
  • Use Cases
  • Database Storage
  • Best Practices
  • Limitations

Integration

• LLM Agent Integration
  • Overview
  • Built-in Agent Prompt
  • Ollama Integration
  • JSON Output for Automation
  • Agent Command Patterns
  • Example: Claude Code Integration
  • Example: GitHub Actions
  • Example: Python Script Integration
  • Best Practices
  • Troubleshooting
• JSON Output
  • Enabling JSON Output
  • Output Formats
  • Working with JSON
  • Error Handling
  • Best Practices
  • DateTime Format
• Automation
  • Shell Scripting
  • Common Automation Tasks
  • CI/CD Integration
  • Pre-commit Hooks
  • Cron Jobs
  • Monitoring Integration
  • Best Practices

API Reference

• Models API
  • Enumerations
  • Data Classes
  • Usage Examples
• Repository API
  • IssueRepository
  • Complete Example
• CLI API
  • CLI Class
  • Main Function
  • Usage Example
• Database API
  • Connection Management
  • Schema Setup
  • Database Schema
  • Default Database Location
  • Custom Database Paths
  • In-Memory Database
  • Transaction Safety
  • Backup and Restore
  • Performance Considerations

Community

• Contributing
• Changelog

About IssueDB

IssueDB is a lightweight, zero-dependency issue tracking system that runs entirely from your command line. Each project directory gets its own SQLite database, so your issues live where your code lives.

Key Features

• Per-Directory Databases: Each directory has its own issuedb.sqlite database

• Simple Issue Management: Create, update, delete, and list issues

• Comments System: Add notes and resolution comments to issues

• Bulk Operations: Create, update, or close multiple issues from JSON

• Priority Levels: Categorize issues as low, medium, high, or critical

• Status Tracking: Track issues through open, in-progress, and closed states

• FIFO Queue Management: Get the next issue to work on based on priority and creation date

• Full-text Search: Search issues by keyword in title and description

• Summary & Reports: Aggregate statistics and detailed breakdowns

• Audit Logging: Complete immutable history of all changes

• JSON Output: Machine-readable output for scripting and automation

• LLM Agent Integration: Built-in prompt for programmatic usage by AI agents

• Natural Language Interface: Ollama integration for conversational issue management

• Zero Dependencies: Uses only Python standard library

Why IssueDB?

IssueDB is designed for developers who want:

1. Simplicity: No servers, no configuration files, no accounts

2. Speed: Everything runs locally on SQLite

3. Portability: Just a single database file per project

4. Automation: Full JSON output and LLM agent support

5. Auditability: Complete history of all changes

Perfect for:

• Solo developers managing personal projects

• Small teams that don’t need enterprise issue tracking

• LLM agents that need programmatic issue management

• CI/CD pipelines that need to create/track issues

• Anyone who prefers the command line

Quick Example

# Create an issue
issuedb-cli create -t "Fix login bug" --priority high

# List open issues
issuedb-cli list -s open

# Get the next issue to work on
issuedb-cli get-next

# Add a comment and close
issuedb-cli comment 1 -t "Fixed by updating auth config"
issuedb-cli update 1 -s closed

Indices and tables

• Index

• Module Index

• Search Page